diff options
Diffstat (limited to 'doc')
135 files changed, 17288 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 00000000..6812bd2d --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +SUBDIRS = $(AUTODIRS) + diff --git a/doc/artsbuilder/Makefile.am b/doc/artsbuilder/Makefile.am new file mode 100644 index 00000000..c0ba5446 --- /dev/null +++ b/doc/artsbuilder/Makefile.am @@ -0,0 +1,5 @@ + +SUBDIRS = $(AUTODIRS) +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/artsbuilder/apis.docbook b/doc/artsbuilder/apis.docbook new file mode 100644 index 00000000..65de23be --- /dev/null +++ b/doc/artsbuilder/apis.docbook @@ -0,0 +1,357 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-apis"> +<title>&arts; Application Programming Interfaces</title> + +<sect1 id="api-overview"> +<title>Overview</title> +<para> +aRts is not only a piece of software, it also provides a variety of APIs +for a variety of purposes. In this section, I will try to describe the "big +picture", a brief glance what those APIs are supposed to do, and how they +interact. +</para> + +<para> +There is one important distinction to make: most of the APIs are <emphasis> +language and location independent</emphasis> because they are specified as +<emphasis>mcopidl</emphasis>. +That is, you can basically use the services they offer from any language, +implement them in any language, and you will not have to care whether you +are talking to local or remote objects. Here is a list of these first: +</para> + + +<variablelist> +<varlistentry> +<term>core.idl</term> + <listitem><para> + Basic definitions that form the core of the MCOP functionality, such as + the protocol itself, definitions of the object, the trader, the flow + system and so on. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>artsflow.idl</term> + + <listitem><para> + These contain the flow system you will use for connecting audio streams, the + definition of <emphasis>Arts::SynthModule</emphasis> which is the base for + any interface that has streams, and finally a few useful audio objects + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>kmedia2.idl</term> + + + <listitem><para> + Here, an object that can play a media, <emphasis>Arts::PlayObject</emphasis> + gets defined. Media players such as the KDE media player noatun will be able + to play any media for which a PlayObject can be found. So it makes sense to + implement PlayObjects for various formats (such as mp3, mpg video, midi, wav, + ...) on that base, and there are a lot already. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>soundserver.idl</term> + + <listitem><para> + Here, an interface for the system wide sound server artsd is defined. The + interface is called <emphasis>Arts::SoundServer</emphasis>, which implements + functionality like accepting streams from the network, playing samples, + creating custom other aRts objects and so on. Network transparency is + implied due to the use of MCOP (as for everything else here). + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>artsbuilder.idl</term> + <listitem><para> + This module defines basic flow graph functionality, that is, combining + simpler objects to more complex ones, by defining a graph of them. It defines + the basic interface <emphasis>Arts::StructureDesc</emphasis>, + <emphasis>Arts::ModuleDesc</emphasis> and <emphasis>Arts::PortDesc</emphasis> + which contain a description of a structure, module, and port. There is also + a way to get a "living network of objects" out of these connection and value + descriptions, using a factory. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>artsmidi.idl</term> + + <listitem><para> + This module defines basic midi functionality, like objects that produce + midi events, what is a midi event, an <emphasis>Arts::MidiManager</emphasis> + to connect the producers and consumers of midi events, and so on. As always + network transparency implied. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>artsmodules.idl</term> + <listitem><para> + Here are various additional filters, oscillators, effects, delays and + so on, everything required for real useful signal processing, and to + build complex instruments and effects out of these basic building blocks. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>artsgui.idl</term> + + <listitem><para> + This cares about visual objects. It defines the basic type <emphasis> + Arts::Widget</emphasis> from which all GUI modules derive. This will produce + toolkit independency, and ... visual GUI editing, and serializable GUIs. + Also, as the GUI elements have normal attributes, their values can be + straight forward connected to some signal processing modules. (I.e. the + value of a slider to the cutoff of a filter). As always: network transparent. + </para></listitem> + +</varlistentry> + +</variablelist> +<para> +Where possible, aRts itself is implemented using IDL. On the other hand, there +are some <emphasis>language specific</emphasis> APIs, using either plain C++ or +plain C. It is usually wise to use IDL interfaces where possible, and the +other APIs where necessary. Here is a list of language specific APIs: +</para> + +<variablelist> + +<varlistentry> +<term>KNotify, KAudioPlayer (included in libkdecore)</term> + + <listitem><para> + These are convenience KDE APIs for the simple and common common case, where + you just want to play a sample. The APIs are plain C++, Qt/KDE optimized, + and as easy as it can get. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>libartsc</term> + <listitem><para> + Plain C interface for the sound server. Very useful for porting legacy + applications. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>libmcop</term> + + <listitem><para> + Here all magic for MCOP happens. The library contains the basic things you + need to know for writing a simple MCOP application, the dispatcher, timers, + iomanagement, but also the internals to make the MCOP protocol itself work. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>libartsflow</term> + <listitem><para> + Besides the implementation of artsflow.idl, some useful utilities like + sampling rate conversion. + </para></listitem> + +</varlistentry> + +<varlistentry> +<term>libqiomanager</term> + + <listitem><para> + Integration of MCOP into the Qt event loop, when you write Qt applications + using MCOP. + </para></listitem> + +</varlistentry> + +</variablelist> + + + +</sect1> +<sect1 id="knotify"> +<title>knotify</title> +<para> +Not yet written +</para> +</sect1> + +<sect1 id="kaudioplayer"> +<title>kaudioplayer</title> +<para> +Not yet written +</para> +</sect1> + +<sect1 id="libkmid"> +<title>libkmid</title> +<para> +Not yet written +</para> +</sect1> + +<sect1 id="kmedia2"> +<title>kmedia2</title> +<para> +Not yet written +</para> +</sect1> + +<sect1 id="soundserver"> +<title>sound server</title> +<para> +Not yet written +</para> +</sect1> + +<sect1 id="artsflow"> +<title>artsflow</title> +<para> +Not yet written +</para> +</sect1> + +<sect1 id="capi"> +<title>C <acronym>API</acronym></title> + +<sect2 id="capiintro"> +<title>Introduction</title> + +<para> The &arts; C <acronym>API</acronym> was designed to make it easy to +writing and port plain C applications to the &arts; sound server. It provides +streaming functionality (sending sample streams to +<application>artsd</application>), either blocking or non-blocking. For most +applications you simply remove the few system calls that deal with your audio +device and replace them with the appropriate &arts; calls.</para> + +<para>I did two ports as a proof of concept: <application>mpg123</application> +and <application>quake</application>. You can get the patches from <ulink +url="http://space.twc.de/~stefan/kde/download/artsc-patches.tar.gz">here</ulink>. +Feel free to submit your own patches to the maintainer of &arts; or of +multimedia software packages so that they can integrate &arts; support into +their code.</para> + +</sect2> + +<sect2 id="capiwalkthru"> +<title>Quick Walkthrough</title> + +<para>Sending audio to the sound server with the <acronym>API</acronym> is very +simple:</para> +<procedure> +<step><para>include the header file using <userinput>#include +<artsc.h></userinput></para></step> +<step><para>initialize the <acronym>API</acronym> with +<function>arts_init()</function></para></step> +<step><para>create a stream with +<function>arts_play_stream()</function></para></step> +<step><para>configure specific parameters with +<function>arts_stream_set()</function></para></step> +<step><para>write sampling data to the stream with +<function>arts_write()</function></para></step> +<step><para>close the stream with +<function>arts_close_stream()</function></para></step> +<step><para>free the <acronym>API</acronym> with +<function>arts_free()</function></para></step> +</procedure> + +<para>Here is a small example program that illustrates this:</para> + +<programlisting> +#include <stdio.h> +#include <artsc.h> +int main() +{ + arts_stream_t stream; + char buffer[8192]; + int bytes; + int errorcode; + + errorcode = arts_init(); + if (errorcode < 0) + { + fprintf(stderr, "arts_init error: %s\n", arts_error_text(errorcode)); + return 1; + } + + stream = arts_play_stream(44100, 16, 2, "artsctest"); + + while((bytes = fread(buffer, 1, 8192, stdin)) > 0) + { + errorcode = arts_write(stream, buffer, bytes); + if(errorcode < 0) + { + fprintf(stderr, "arts_write error: %s\n", arts_error_text(errorcode)); + return 1; + } + } + + arts_close_stream(stream); + arts_free(); + + return 0; +} +</programlisting> +</sect2> + +<sect2 id="capiartscconfig"> +<title>Compiling and Linking: <application>artsc-config</application></title> + +<para>To easily compile and link programs using the &arts; C +<acronym>API</acronym>, the <application>artsc-config</application> utility is +provided which knows which libraries you need to link and where the includes +are. It is called using</para> + +<screen> +<userinput><command>artsc-config</command> <option>--libs</option></userinput> +</screen> + +<para>to find out the libraries and </para> + +<screen> +<userinput><command>artsc-config</command> <option>--cflags</option></userinput> +</screen> + +<para>to find out additional C compiler flags. The example above could have been + +compiled using the command line:</para> + +<screen> +<userinput><command>cc</command> <option>-o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`</option></userinput> + +<userinput><command>cc</command> <option>-o artsctest</option> <option>artsctest.c</option> <option>`artsc-config --cflags`</option> <option>`artsc-config --libs`</option></userinput> +</screen> + +</sect2> + +<sect2 id="c-api-reference"> +<title>Library Reference</title> + +<para> +[TODO: generate the documentation for artsc.h using kdoc] +</para> + +</sect2> + +</sect1> +</chapter> diff --git a/doc/artsbuilder/arts-structure.png b/doc/artsbuilder/arts-structure.png Binary files differnew file mode 100644 index 00000000..8f6f3131 --- /dev/null +++ b/doc/artsbuilder/arts-structure.png diff --git a/doc/artsbuilder/artsbuilder.docbook b/doc/artsbuilder/artsbuilder.docbook new file mode 100644 index 00000000..b5f4f68c --- /dev/null +++ b/doc/artsbuilder/artsbuilder.docbook @@ -0,0 +1,864 @@ +<chapter id="artsbuilder"> +<title>&arts-builder;</title> + +<sect1 id="overview"> +<title>Overview</title> + +<para> +First of all, when trying to run &arts-builder; , you should also be +running the sound server (&artsd;). Usually, when you use &kde; 2.1, +this should already be the case. If not, you can configure the automatic +sound server startup in &kcontrol; under +<menuchoice><guilabel>Sound</guilabel><guilabel>Sound +Server</guilabel></menuchoice>. +</para> + +<para> +When you are running &arts;, it always runs small modules. &arts-builder; +is a tool to create new structures of small connected modules. You +simply click the modules inside the grid. To do so, choose them from the +<guimenu>Modules</guimenu> menu, and then click somewhere in the +green-gray plane. +</para> + +<para> +Modules usually have ports (where usually audio signals are flowing in +or out). To connect two ports, click on the first, which causes it to +turn orange, and then click on the second. You can only connect an input +port (on the upper side of a module) with an output port (on the lower +side of a module). If you want to assign a fixed value to a port (or +disconnect it), do so by double clicking on the port. +</para> + +</sect1> + +<sect1 id="artsbuilder-tutorial"> +<title>Tutorial</title> + +<sect2 id="step-1"> +<title>Step 1</title> + +<para> +Start &arts-builder;. +</para> + +<para> +You need a Synth_AMAN_PLAY-module to hear the output you +are creating. So create a Synth_AMAN_PLAY-module by +selecting <menuchoice><guimenu>Modules</guimenu> +<guisubmenu>Synthesis</guisubmenu> <guisubmenu>SoundIO</guisubmenu> +<guisubmenu>Synth_AMAN_PLAY</guisubmenu></menuchoice> and +clicking on the empty module space. Put it below the fifth line or so, +because we'll add some stuff above. +</para> + +<para> +The module will have a parameter <parameter>title</parameter> (leftmost +port), and <parameter>autoRestoreID</parameter> (besides the leftmost +port) for finding it. To fill these out, doubleclick on these ports, +select constant value and type <userinput>tutorial</userinput> in the +edit box. Click <guibutton>OK</guibutton> to apply. +</para> + +<para> +Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute +structure</guimenuitem> </menuchoice>. You will hear absolutely +nothing. The play module needs some input yet... ;) If you have listened +to the silence for a while, click <guibutton>OK</guibutton> and go to +Step 2 +</para> +</sect2> + +<sect2 id="step-2"> +<title>Step 2</title> + +<para>Create a Synth_WAVE_SIN module (from <menuchoice> +<guimenu>Modules</guimenu> <guimenuitem>Synthesis</guimenuitem> +<guimenuitem>Waveforms</guimenuitem></menuchoice>) +and put it above the Synth_AMAN_PLAY module. (Leave one line +space in between). +</para> + +<para> +As you see, it produces some output, but requires a +<guilabel>pos</guilabel> as input. First lets put the output to the +speakers. Click on the <guilabel>out</guilabel> port of the +Synth_WAVE_SIN and then on the <guilabel>left</guilabel> +port of Synth_AMAN_PLAY. Voila, you have connected two +modules. +</para> + +<para> +All oscillators in &arts; don't require a frequency as input, but a +position in the wave. The position should be between 0 and 1, which maps +for a standard Synth_WAVE_SIN object to the range +0..2*pi. To generate oscillating values from a frequency, a +Synth_FREQUENCY modules is used. +</para> + +<para> +Create a Synth_FREQUENCY module (from <menuchoice> +<guimenu>Modules</guimenu> <guimenu>Synthesis</guimenu> +<guimenu>Oscillation & Modulation</guimenu> </menuchoice>) and +connect it's <quote>pos</quote> output to the <quote>pos</quote> input +of your Synth_WAVE_SIN. Specify the frequency port of the +FREQUENCY generator as constant value 440. +</para> + + +<para> +Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute +structure</guimenuitem></menuchoice>. You will hear a sinus wave at 440 +Hz on one of your speakers. If you have listened to it for a while, +click <guibutton>OK</guibutton> and go to Step 3. +</para> + +</sect2> + +<sect2 id="step-3"> +<title>Step 3</title> + +<para> +Ok, it would be nicer if you would hear the sin wave on both speakers. +Connect the right port of Synth_PLAY to the outvalue of the +Synth_WAVE_SIN as well. +</para> + +<para>Create a Synth_SEQUENCE object (from +<menuchoice><guimenu>Modules</guimenu> +<guisubmenu>Synthesis</guisubmenu><guisubmenu>Midi & +Sequencing</guisubmenu></menuchoice>). It should be at the top of the +screen. If you need more room you can move the other modules by +selecting them (to select multiple modules use &Shift;), and dragging +them around. +</para> + +<para> +Now connect the frequency output of Synth_SEQUENCE to the +frequency input of the Synth_FREQUENCY module. Then specify the +sequence speed as constant value 0.13 (the speed is the leftmost port). +</para> + +<para> +Now go to the rightmost port (sequence) of Synth_SEQUENCE and +type in as constant value <userinput>A-3;C-4;E-4;C-4;</userinput> this +specifies a sequence. More to that in the Module Reference. +</para> + +<note> +<para>Synth_SEQUENCE really <emphasis>needs</emphasis> a sequence +and the speed. Without that you'll perhaps get core dumps. +</para> +</note> + +<para> +Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute +Structure</guimenuitem></menuchoice>. You will hear a nice sequence +playing. If you have enjoyed the feeling, click +<guibutton>OK</guibutton> and go to Step 4. +</para> +</sect2> + +<sect2 id="step-4"> +<title>Step 4</title> + +<para>Create a Synth_PSCALE module (from +<menuchoice><guimenu>Modules</guimenu> +<guisubmenu>Synthesis</guisubmenu> <guisubmenu>Envelopes</guisubmenu> +</menuchoice>). Disconnect the outvalue of the SIN wave by doubleclicking it +and choosing <guilabel>not connected</guilabel>. Connect +</para> + +<orderedlist><listitem> +<para>The SIN outvalue to the PSCALE invalue</para> +</listitem> +<listitem> +<para>The PSCALE outvalue to the AMAN_PLAY left</para> +</listitem> +<listitem> +<para>The PSCALE outvalue to the AMAN_PLAY right</para> +</listitem> +<listitem> +<para>The SEQUENCE pos to the PSCALE pos</para> +</listitem> +</orderedlist> + +<para> +Finally, set the PSCALE top to some value, for instance 0.1. +</para> + +<para> +How that works now: The Synth_SEQUENCE gives additional +information about the position of the note it is playing right now, +while 0 means just started and 1 means finished. The Synth_PSCALE +module will scale the audio stream that is directed through it from a +volume 0 (silent) to 1 (original loudness) back to 0 (silent). According +to the position. The position where the peak should occur can be given +as pos. 0.1 means that after 10% of the note has been played, the +volume has reached its maximum, and starts decaying afterwards. +</para> + + +<para>Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute +Structure</guimenuitem></menuchoice>. You will hear a nice sequence +playing. If you have enjoyed the feeling, click +<guibutton>OK</guibutton> and go to Step 5. +</para> + +</sect2> + +<sect2 id="step-5-starting-to-beam-data-around"> +<title>Step 5: Starting to beam data around ;)</title> + +<para>Start another &arts-builder;</para> + +<para> +Put a Synth_AMAN_PLAY into it, configure it to a sane +name. Put a Synth_BUS_DOWNLINK into it and:</para> + +<orderedlist> +<listitem> +<para> +Set Synth_BUS_DOWNLINK bus to audio (that is just a name, +call it fred if you like) +</para> +</listitem> +<listitem> +<para> +Connect Synth_BUS_DOWNLINK left to +Synth_AMAN_PLAY left +</para> +</listitem> +<listitem> +<para> +Connect Synth_BUS_DOWNLINK right to +Synth_AMAN_PLAY right +</para> +</listitem> +</orderedlist> + +<para> +Start executing the structure. As expected, you hear nothing, ... not +yet. +</para> + +<para> +Go back to the structure with the Synth_WAVE_SIN stuff and +replace the Synth_AMAN_PLAY module by an +Synth_BUS_UPLINK, and configure the name to audio (or fred +if you like). Deleting modules works with selecting them and choosing +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>delete</guimenuitem></menuchoice> from the menu (or +pressing the <keycap>Del</keycap> key). +</para> + +<para> +Hit <menuchoice><guimenu>File</guimenu> <guilabel>Execute +structure</guilabel></menuchoice>. You will hear the sequence with +scaled notes, transported over the bus. +</para> + +<para> +If you want to find out why something like this can actually be useful, +click <guibutton>OK</guibutton> (in the &arts-builder; that is executing +the Synth_SEQUENCE stuff, you can leave the other one running) +and go to Step 6. +</para> +</sect2> + +<sect2 id="step-6-beaming-for-advanced-users"> +<title>Step 6: Beaming for advanced users</title> + +<para> +Choose <menuchoice><guimenu>File</guimenu><guimenuitem>Rename</guimenuitem> +</menuchoice> structure from the menu of the artsbuilder which +contains the Synth_SEQUENCE stuff, and call it tutorial. Hit +<guibutton>OK</guibutton>. +</para> + +<para> +Choose <menuchoice><guimenu>File</guimenu> <guimenuitem>Save</guimenuitem> +</menuchoice> +</para> + +<para> +Start yet another &arts-builder; and choose +<menuchoice><guimenu>File</guimenu><guimenuitem>Load</guimenuitem> +</menuchoice>, and load the tutorial again. +</para> + +<para> +Now you can select +<menuchoice><guimenu>File</guimenu><guimenuitem>Execute +structure</guimenuitem> </menuchoice>in both &arts-builder;s having that +structure. You'll now hear two times the same thing. Depending on the +time when you start it it will sound more or less nice. +</para> + +<para> +Another thing that is good to do at this point in time is: start +&noatun;, and play some <literal role="extension">mp3</literal>. Start +&artscontrol;. Go to +<menuchoice><guimenu>View</guimenu><guimenuitem>View audio +manager</guimenuitem></menuchoice>. What you will see is &noatun; and +your <quote>tutorial</quote> playback structure playing something. The +nice thing you can do is this: doubleclick on &noatun;. You'll now get a +list of available busses. And see? You can assign &noatun; to send it's +output via the audio bus your tutorial playback structure provides. +</para> +</sect2> + +<sect2 id="step-7-midi-synthesis"> +<title>Step 7: Midi synthesis</title> + +<para> +Finally, now you should be able to turn your sin wave into an real +instrument. This only makes sense if you have something handy that could +send &MIDI; events to &arts;. I'll describe here how you can use some +external keyboard, but a midibus aware sequence like &brahms; will work +as well. +</para> + +<para> +First of all, clean up on your desktop until you only have one +&arts-builder; with the sine wave structure running (not executing). +Then, three times go to <menuchoice><guimenu>Ports</guimenu> +<guisubmenu>Create IN audio signal</guisubmenu></menuchoice>, and three +times to <menuchoice><guimenu>Ports</guimenu> <guisubmenu>Create OUT +audio signal</guisubmenu></menuchoice>. Place the ports somewhere. +</para> + +<para> +Finally, go to <menuchoice><guimenu>Ports</guimenu> <guilabel>Change +positions and names</guilabel></menuchoice> and call the ports +frequency, velocity, pressed, left, right, done. +</para> + +<para> +Finally, you can delete the Synth_SEQUENCE module, and rather +connect connect the frequency input port of the structure to the +Synth_FREQUENCY frequency port. Hm. But what do do about +pos?</para> <para>We don't have this, because with no algorithm in the +world, you can predict when the user will release the note he just +pressed on the midi keyboard. So we rather have a pressed parameter +instead that just indicates wether the user still holds down the +key. (pressed = 1: key still hold down, pressed = 0: key +released) +</para> + +<para> +That means the Synth_PSCALE object also must be replaced +now. Plug in a Synth_ENVELOPE_ADSR instead (from +<menuchoice><guimenu>Modules</guimenu> +<guisubmenu>Synthesis</guisubmenu> <guisubmenu>Envelopes</guisubmenu> +</menuchoice>). Connect: +</para> + +<orderedlist> +<listitem> +<para>The pressed structure input to the ADSR active</para> +</listitem> +<listitem> +<para>The SIN outvalue to the ADSR invalue</para> +</listitem> +<listitem> +<para>The ADSR outvalue to the left structure output</para> +</listitem><listitem> +<para>The ADSR outvalue to the right structure output</para> +</listitem> +</orderedlist> + +<para> +Set the parameters attack to 0.1, decay to 0.2, sustain to 0.7, release +to 0.1. +</para> + +<para> +Another thing we need to think of is that the instrument structure +somehow should know when it is ready playing and then be cleaned up, +because otherwise it would be never stopped even if the note has been +released. Fortunately, the ADSR envelope knows when the will be nothing +to hear anymore, since it anyway scales the signal to zero at some point +after the note has been released. +</para> + +<para> +This is indicated by setting the done output to 1. So connect this to +the done output of the structure. The structure will be removed as soon +as done goes up to 1. +</para> + +<para> +Rename your structure to instrument_tutorial (from <menuchoice><guimenu> +File</guimenu> <guimenuitem>Rename +structure</guimenuitem></menuchoice>. Then, save it using save as (the +default name offered should be instrument_tutorial +now).</para><para>Start artscontrol, and go to +<menuchoice><guimenu>View</guimenu><guimenuitem>Midi +Manager</guimenuitem></menuchoice>, and choose +<menuchoice><guimenu>Add</guimenu><guimenuitem>aRts Synthesis Midi +Output</guimenuitem></menuchoice>. Finally, you should be able to +select your instrument (tutorial) here. +</para> + +<para> +Open a terminal and type +<userinput><command>midisend</command></userinput>. You'll see that +<command>midisend</command> and the instrument are listed now in the +&arts; &MIDI; manager. After selecting both and hitting +<guibutton>connect</guibutton>, we're finally done. Take your keyboard +and start playing (of course it should be connected to your computer). +</para> +</sect2> + +<sect2 id="suggestions"> +<title>Suggestions</title> + +<para> +You now should be able to work with &arts;. Here are a few tips what you +could try to improve with your structures now: +</para> + +<itemizedlist> +<listitem> +<para> +Try using other things than a SIN wave. When you plug in a TRI wave, you +will most likely think the sound is not too nice. But try appending a +SHELVE_CUTOFF filter right after the TRI wave to cut the +frequenciesabove a certain frequency (try something like 1000 Hz, or +even better two times the input frequency or input frequency+200Hz or +something like that). +</para> +</listitem> +<listitem> +<para> +Try using more than one oscillator. Synth_XFADE can be used to +cross fade (mix) two signals, Synth_ADD to add them. +</para> +</listitem> +<listitem> +<para> +Try setting the frequencies of the oscillators to not exactly the same +value, that gives nice oscillations. +</para> +</listitem> +<listitem> +<para> +Experiment with more than one envelope. +</para> +</listitem> +<listitem> +<para> +Try synthesizing instruments with different output left and right. +</para> +</listitem> +<listitem> +<para> +Try postprocessing the signal after it comes out the bus downlink. You +could for instance mix a delayed version of the signal to the original +to get an echo effect. +</para> +</listitem> +<listitem> +<para> +Try using the velocity setting (its the strength with which the note has +been pressed, you could also say volume). The special effect is always +when this not only modifies the volume of the resulting signal, but as +well the sound of the instrument (for instance the cutoff frequency). +</para> +</listitem> +<listitem> +<para>...</para> +</listitem> +</itemizedlist> + +<para> +If you have created something great, please consider providing it for +the &arts; web page. Or for inclusion into the next release. +</para> +</sect2> + +</sect1> + +<sect1 id="artsbuilder-examples"> +<title>Examples</title> + +<para> +&arts-builder; comes with several examples, which can be opened through +<menuchoice><guimenu>File</guimenu><guimenuitem>Open +Example...</guimenuitem> </menuchoice>. Some of them are in the +folder, some of them (which for some reason don't work with the +current release) are left in the todo folder. +</para> +<para> +The examples fall into several categories: +</para> + +<itemizedlist> +<listitem> +<para> +Standalone examples illustrating how to use each of the built-in +arts modules (named <filename>example_*.arts</filename>). These +typically send some output to a sound card. +</para> +</listitem> + +<listitem> +<para> +Instruments built from lower level arts modules (named +<filename>instrument_*.arts</filename>). These following a standard +convention for input and output ports so they can be used by the &MIDI; +manager in &artscontrol;. +</para> +</listitem> + +<listitem> +<para> +Templates for creating new modules (names +<filename>template_*.arts</filename>). +</para> +</listitem> + +<listitem> +<para> +Effects which can be used as reusable building blocks (named +<filename>effect_*.arts</filename>) [ all in todo ] +</para> +</listitem> + +<listitem> +<para> +Mixer elements used for creating mixers, including graphical +controls (named <filename>mixer_element_*.arts</filename>). [ all in todo ] +</para> +</listitem> + +<listitem> +<para> +Miscellaneous modules that don't fit into any of the above categories. +</para> +</listitem> +</itemizedlist> + +<variablelist> +<title>Detailed Description Of Each Module:</title> +<varlistentry> +<term><filename>example_stereo_beep.arts</filename></term> +<listitem> +<para> +Generates a 440Hz sine wave tone in the left channel and an 880Hz sine +wave tone in the right channel, and sends it to the sound card +output. This is referenced in the &arts; documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_sine.arts</filename></term> +<listitem> +<para> +Generates a 440 Hz sine wave. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_pulse.arts</filename></term> +<listitem> +<para> +Generates a 440 Hz pulse wave with a 20% duty cycle. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_softsaw.arts</filename></term> +<listitem> +<para> +Generates a 440 Hz sawtooth wave. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_square.arts</filename></term> +<listitem> +<para> +Generates a 440 Hz square wave. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_tri.arts</filename></term> +<listitem> +<para> +Generates a 440 Hz triangle wave. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_noise.arts</filename></term> +<listitem> +<para> +Generates white noise. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_dtmf1.arts</filename></term> +<listitem> +<para> +Generates a dual tone by producing 697 and 1209 Hz sine waves, scaling +them by 0.5, and adding them together. This is the DTMF tone for the +digit "1" on a telephone keypad. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_atan_saturate.arts</filename></term> +<listitem> +<para> +Runs a triangle wave through the atan saturate filter. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_autopanner.arts</filename></term> +<listitem> +<para> +Uses an autopanner to pan a 400 Hz sine wave between the left and right +speakers at a 2 Hz rate. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_brickwall.arts</filename></term> +<listitem> +<para> +Scales a sine wave by a factor of 5 and then runs it through a brickwall +limiter. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_bus.arts</filename></term> +<listitem> +<para> +Downlinks from a bus called <quote>Bus</quote> and uplinks to the bus +<quote>out_soundcard</quote> with the left and right channels reversed. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_cdelay.arts</filename></term> +<listitem> +<para> +Downlinks from a bus called <quote>Delay</quote>, uplinks the right +channel through a 0.5 second cdelay, and the left channel unchanged. You +can use &artscontrol; to connect the effect to a sound player and +observe the results. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_delay.arts</filename></term> +<listitem> +<para> +This is the same as <filename>example_cdelay.arts</filename> but used +the delay effect. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_capture_wav.arts</filename></term> +<listitem> +<para> +This uses the Synth_CAPTURE_WAV to save a 400 Hz sine wave as a wav +file. Run the module for a few seconds, and then examine the file +created in <filename class="directory">/tmp</filename>. You can play the +file with a player such as <application>kaiman</application>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_data.arts</filename></term> +<listitem> +<para> +This uses the Data module to generate a constant stream of the value +<quote>3</quote> and sends it to a Debug module to periodically display +it. It also contains a Nil module, illustrating how it can be used to do +nothing at all. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_adsr.arts</filename></term> +<listitem> +<para> +Shows how to create a simple instrument sound using the Envelope Adsr +module, repetitively triggered by a square wave. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_fm.arts</filename></term> +<listitem> +<para> +This uses the FM Source module to generate a 440 Hz sine wave which is +frequency modulated at a 5 Hz rate. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_freeverb.arts</filename></term> +<listitem> +<para> +This connects the Freeverb effect from a bus downlink to a bus +outlink. You can use artscontrol to connect the effect to a sound player +and observe the results. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_flanger.arts</filename></term> +<listitem> +<para> +This implements a simple flanger effect (it doesn't appear to work yet, +though). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_moog.arts</filename></term> +<listitem> +<para> +This structure combines the two channels from a bus into one, passes it +though the Moog VCF filter, and sends it out the out_soundcard bus. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_pitch_shift.arts</filename></term> +<listitem> +<para> +This structure passes the left channel of sound card data through the +Pitch Shift effect. Adjust the speed parameter to vary the effect. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_rc.arts</filename></term> +<listitem> +<para> +This structure passes a white noise generator though an RC filter and +out to the sound card. By viewing the FFT Scope display in artscontrol +you can see how this varies from an unfiltered noise waveform. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_sequence.arts</filename></term> +<listitem> +<para> +This demonstrates the Sequence module by playing a sequence of notes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_shelve_cutoff.arts</filename></term> +<listitem> +<para> +This structure passes a white noise generator though a Shelve Cutoff +filter and out to the sound card. By viewing the FFT Scope display in +artscontrol you can see how this varies from an unfiltered noise +waveform. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_equalizer.arts</filename></term> +<listitem> +<para> +This demonstrates the Std_Equalizer module. It boosts the low and high +frequencies by 6 dB. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_tremolo.arts</filename></term> +<listitem> +<para> +This demonstrates the Tremolo effect. It modulates the left and right +channels using a 10 Hz tremolo. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_xfade.arts</filename></term> +<listitem> +<para> +This example mixes 440 and 880 Hz sine waves using a cross fader. +Adjust the value of the cross fader's percentage input from -1 to 1 to +control the mixing of the two signals. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_pscale.arts</filename></term> +<listitem> +<para> +This illustrates the Pscale module (I'm not sure if this is a +meaningful example). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>example_play_wav.arts</filename></term> +<listitem> +<para> +This illustrates the Play Wave module. You will need to +enter the full path to a <literal role="extension">.wav</literal> file +as the filename parameter. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>example_multi_add.arts</term> +<listitem> +<para> +This shows the Multi Add module which accepts any number of inputs. It +sums three Data modules which produce inputs of 1, 2, and 3, and +displays the result 6. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +</chapter> diff --git a/doc/artsbuilder/detail.docbook b/doc/artsbuilder/detail.docbook new file mode 100644 index 00000000..c7ed7319 --- /dev/null +++ b/doc/artsbuilder/detail.docbook @@ -0,0 +1,1765 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-in-detail"> +<title>&arts; in Detail</title> + +<sect1 id="architecture"> +<title>Architecture</title> + +<mediaobject> +<imageobject> +<imagedata fileref="arts-structure.png" format="PNG"/> +</imageobject> +<textobject><phrase>The &arts; structure.</phrase></textobject> +</mediaobject> +</sect1> + +<sect1 id="modules-ports"> +<title>Modules & Ports</title> + +<para> +The idea of &arts; is, that synthesis can be done using small modules, +which only do one thing, and then recombine them in complex +structures. The small modules normally have inputs, where they can get +some signals or parameters, and outputs, where they produce some +signals. +</para> + +<para> +One module (Synth_ADD) for instance just takes the two signals at +it's input and adds them together. The result is available as output +signal. The places where modules provide their input/output signals are +called ports. +</para> + +</sect1> + +<sect1 id="structures"> +<title>Structures</title> + +<para> +A structure is a combination of connected modules, some of which may +have parameters coded directly to their input ports, others which may be +connected, and others, which are not connected at all. +</para> + +<para> +What you can do with &arts-builder; is describing structures. You +describe, which modules you want to be connected with which other +modules. When you are done, you can save that structure description to a +file, or tell &arts; to create such a structure you described (Execute). +</para> + +<para> +Then you'll probably hear some sound, if you did everything the right +way. +</para> +</sect1> + +<!-- TODO + +<sect1 id="streams"> +<title>Streams</title> +<para> +</para> +</sect1> + +--> + +<sect1 id="latency"> +<title>Latency</title> + +<sect2 id="what-islatency"> +<title>What Is Latency?</title> + +<para> +Suppose you have an application called <quote>mousepling</quote>(that +should make a <quote>pling</quote> sound if you click on a button. The +latency is the time between your finger clicking the mouse button and +you hearing the pling. The latency in this setup composes itself out of +certain latencies, that have different causes. +</para> + +</sect2> + +<sect2 id="latenbcy-simple"> +<title>Latency in Simple Applications</title> + +<para> +In this simple application, latency occurs at these places: +</para> + +<itemizedlist> + +<listitem> +<para> +The time until the kernel has notified the X11 server that a mouse +button was pressed. +</para> +</listitem> + +<listitem> +<para> +The time until the X11 server has notified your application that a mouse +button was pressed. +</para> +</listitem> + +<listitem> +<para> +The time until the mousepling application has decided that this button +is worth playing a pling. +</para> +</listitem> + +<listitem> +<para> +The time it takes the mousepling application to tell the soundserver +that it should play a pling. +</para> +</listitem> + +<listitem> +<para> +The time it takes for the pling (which the soundserver starts mixing to +the other output at once) to go through the buffered data, until it +really reaches the position where the soundcard plays. +</para> +</listitem> + +<listitem> +<para> +The time it takes the pling sound from the speakers to reach your ear. +</para> +</listitem> +</itemizedlist> + +<para> +The first three items are latencies external to &arts;. They are +interesting, but beyond the scope of this document. Nevertheless be +aware that they exist, so that even if you have optimized everything +else to really low values, you may not necessarily get exactly the +result you calculated. +</para> + +<para> +Telling the server to play something involves usually one single &MCOP; +call. There are benchmarks which confirm that, on the same host with +unix domain sockets, telling the server to play something can be done +about 9000 times in one second with the current implementation. I expect +that most of this is kernel overhead, switching from one application to +another. Of course this value changes with the exact type of the +parameters. If you transfer a whole image with one call, it will be +slower than if you transfer only one long value. For the returncode the +same is true. However for ordinary strings (such as the filename of the +<literal role="extension">wav</literal> file to play) this shouldn't be +a problem. +</para> + +<para> +That means, we can approximate this time with 1/9000 sec, that is below +0.15 ms. We'll see that this is not relevant. +</para> + +<para> +Next is the time between the server starting playing and the soundcard +getting something. The server needs to do buffering, so that when other +applications are running, such as your X11 server or +<quote>mousepling</quote> application no dropouts are heard. The way +this is done under &Linux; is that there are a number fragments of a +size. The server will refill fragments, and the soundcard will play +fragments. +</para> + +<para> +So suppose there are three fragments. The server refills the first, the +soundcard starts playing it. The server refills the second. The server +refills the third. The server is done, other applications can do +something now. +</para> + +<para> +As the soundcard has played the first fragment, it starts playing the +second and the server starts refilling the first. And so on. +</para> + +<para> +The maximum latency you get with all that is (number of fragments)*(size +of each fragment)/(samplingrate * (size of each sample)). Suppose we +assume 44kHz stereo, and 7 fragments a 1024 bytes (the current aRts +defaults), we get 40 ms. +</para> + +<para> +These values can be tuned according to your needs. However, the +<acronym>CPU</acronym> usage increases with smaller latencies, as the +sound server needs to refill the buffers more often, and in smaller +parts. It is also mostly impossible to reach better values without +giving the soundserver realtime priority, as otherwise you'll often get +drop-outs. +</para> + +<para> +However, it is realistic to do something like 3 fragments with 256 bytes +each, which would make this value 4.4 ms. With 4.4ms delay the idle +<acronym>CPU</acronym> usage of &arts; would be about 7.5%. With 40ms delay, it would be +about 3% (of a PII-350, and this value may depend on your soundcard, +kernel version and others). +</para> + +<para> +Then there is the time it takes the pling sound to get from the speakers +to your ear. Suppose your distance from the speakers is 2 meters. Sound +travels at a speed of 330 meters per second. So we can approximate this +time with 6 ms. +</para> + +</sect2> + +<sect2 id="latency-streaming"> +<title>Latency in Streaming Applications</title> + +<para> +Streaming applications are those that produce their sound themselves. +Assume a game, which outputs a constant stream of samples, and should +now be adapted to replay things via &arts;. To have an example: when I +press a key, the figure which I am playing jumps, and a boing sound is +played. +</para> + +<para> +First of all, you need to know how &arts; does streaming. Its very +similar to the I/O with the soundcard. The game sends some packets with +samples to the sound server. Lets say three packets. As soon as the +sound server is done with the first packet, it sends a confirmation back +to the game that this packet is done. +</para> + +<para> +The game creates another packet of sound and sends it to the server. +Meanwhile the server starts consuming the second sound packet, and so +on. The latency here looks similar like in the simple case: +</para> + +<itemizedlist> +<listitem> +<para> +The time until the kernel has notified the X11 server that a key was +pressed. +</para> +</listitem> + +<listitem> +<para> +The time until the X11 server has notified the game that a key was +pressed. +</para> +</listitem> + +<listitem> +<para> +The time until the game has decided that this key is worth playing a +boing. +</para> +</listitem> + +<listitem> +<para> +The time until the packet of sound in which the game has started putting +the boing sound is reaching the sound server. +</para> +</listitem> + +<listitem> +<para> +The time it takes for the boing (which the soundserver starts mixing to +the other output at once) to go through the buffered data, until it +really reaches the position where the soundcard plays. +</para> +</listitem> + +<listitem> +<para> +The time it takes the boing sound from the speakers to +reach your ear. +</para> +</listitem> + +</itemizedlist> + +<para> +The external latencies, as above, are beyond the scope of this document. +</para> + +<para> +Obviously, the streaming latency depends on the time it takes all +packets that are used for streaming to be played once. So it is (number +of packets)*(size of each packet)/(samplingrate * (size of each sample)) +</para> + +<para> +As you see that is the same formula as applies for the +fragments. However for games, it makes no sense to do such small delays +as above. I'd say a realistic configuration for games would be 2048 +bytes per packet, use 3 packets. The resulting latency would be 35ms. +</para> + +<para> +This is based on the following: assume that the game renders 25 frames +per second (for the display). It is probably safe to assume that you +won't notice a difference of sound output of one frame. Thus 1/25 second +delay for streaming is acceptable, which in turn means 40ms would be +okay. +</para> + +<para> +Most people will also not run their games with realtime priority, and +the danger of drop-outs in the sound is not to be neglected. Streaming +with 3 packets a 256 bytes is possible (I tried that) - but causes a lot +of <acronym>CPU</acronym> usage for streaming. +</para> + +<para> +For server side latencies, you can calculate these exactly as above. +</para> + +</sect2> + +<sect2 id="cpu-usage"> +<title>Some <acronym>CPU</acronym> usage considerations</title> + +<para> +There are a lot of factors which influence _<acronym>CPU</acronym> usage +in a complex scenario, with some streaming applications and some others, +some plugins on the server etc. To name a few: +</para> + +<itemizedlist> +<listitem> +<para> +Raw <acronym>CPU</acronym> usage by the calculations necessary. +</para> +</listitem> + +<listitem> +<para> +&arts; internal scheduling overhead - how &arts; decides when which +module should calculate what. +</para> +</listitem> + +<listitem> +<para> +Integer to float conversion overhead. +</para> +</listitem> + +<listitem> +<para> +&MCOP;0 protocol overhead. +</para> +</listitem> + +<listitem> +<para> +Kernel: process/context switching. +</para> +</listitem> + +<listitem> +<para> +Kernel: communication overhead +</para> +</listitem> +</itemizedlist> + +<para> +For raw <acronym>CPU</acronym> usage for calculations, if you play two +streams, simultaneously you need to do additions. If you apply a filter, +some calculations are involved. To have a simplified example, adding two +streams involves maybe four <acronym>CPU</acronym> cycles per addition, +on a 350Mhz processor, this is 44100*2*4/350000000 = 0.1% +<acronym>CPU</acronym> usage. +</para> + +<para> +&arts; internal scheduling: &arts; needs to decide which plugin when +calculates what. This takes time. Take a profiler if you are interested +in that. Generally what can be said is: the less realtime you do +(&ie;. the larger blocks can be calculated at a time) the less +scheduling overhead you have. Above calculating blocks of 128 samples at +a time (thus using fragment sizes of 512 bytes) the scheduling overhead +is probably not worth thinking about it. +</para> + +<para> +Integer to float conversion overhead: &arts; uses floats internally as +data format. These are easy to handle and on recent processors not +slower than integer operations. However, if there are clients which play +data which is not float (like a game that should do its sound output via +&arts;), it needs to be converted. The same applies if you want to +replay the sounds on your soundcard. The soundcard wants integers, so +you need to convert. +</para> + +<para> +Here are numbers for a Celeron, approx. ticks per sample, with -O2 +egcs +2.91.66 (taken by Eugene Smith <email>hamster@null.ru</email>). This is +of course highly processor dependant: +</para> + +<programlisting> +convert_mono_8_float: 14 +convert_stereo_i8_2float: 28 +convert_mono_16le_float: 40 +interpolate_mono_16le_float: 200 +convert_stereo_i16le_2float: 80 +convert_mono_float_16le: 80 +</programlisting> + +<para> +So that means 1% <acronym>CPU</acronym> usage for conversion and 5% for +interpolation on this 350 MHz processor. +</para> + +<para> +&MCOP; protocol overheadL &MCOP; does, as a rule of thumb, 9000 +invocations per second. Much of this is not &MCOP;s fault, but relates +to the two kernel causes named below. However, this gives a base to do +calculations what the cost of streaming is. +</para> + +<para> +Each data packet transferred through streaming can be considered one +&MCOP; invocation. Of course large packets are slower than 9000 +packets/s, but its about the idea. +</para> + +<para> +Suppose you use packet sizes of 1024 bytes. Thus, to transfer a stream +with 44kHz stereo, you need to transfer 44100*4/1024 = 172 packets per +second. Suppose you could with 100% cpu usage transfer 9000 packets, +then you get (172*100)/9000 = 2% <acronym>CPU</acronym> usage due to +streaming with 1024 byte packets. +</para> + +<para> +That are approximations. However, they show, that you would be much +better off (if you can afford it for the latency), to use for instance +packets of 4096 bytes. We can make a compact formula here, by +calculating the packet size which causes 100% <acronym>CPU</acronym> usage as +44100*4/9000 = 19.6 samples, and thus getting the quick formula: +</para> + +<para> +streaming <acronym>CPU</acronym> usage in percent = 1960/(your packet size) +</para> + +<para> +which gives us 0.5% <acronym>CPU</acronym> usage when streaming with 4096 byte packets. +</para> + +<para> +Kernel process/context switching: this is part of the &MCOP; protocol +overhead. Switching between two processes takes time. There is new +memory mapping, the caches are invalid, whatever else (if there is a +kernel expert reading this - let me know what exactly are the causes). +This means: it takes time. +</para> + +<para> +I am not sure how many context switches &Linux; can do per second, but +that number isn't infinite. Thus, of the &MCOP; protocol overhead I +suppose quite a bit is due to context switching. In the beginning of +&MCOP;, I did tests to use the same communication inside one process, +and it was much faster (four times as fast or so). +</para> + +<para> +Kernel: communication overhead: This is part of the &MCOP; protocol +overhead. Transferring data between processes is currently done via +sockets. This is convenient, as the usual select() methods can be used +to determine when a message has arrived. It can also be combined with +other I/O sources as audio I/O, X11 server or whatever else easily. +</para> + +<para> +However, those read and write calls cost certainly processor cycles. For +small invocations (such as transferring one midi event) this is probably +not so bad, for large invocations (such as transferring one video frame +with several megabytes) this is clearly a problem. +</para> + +<para> +Adding the usage of shared memory to &MCOP; where appropriate is +probably the best solution. However it should be done transparent to the +application programmer. +</para> + +<para> +Take a profiler or do other tests to find out how much exactly +current audio streaming is impacted by the not using sharedmem. However, +its not bad, as audio streaming (replaying mp3) can be done with 6% +total <acronym>CPU</acronym> usage for &artsd; and +<application>artscat</application> (and 5% for the mp3 +decoder). However, this includes all things from the necessary +calculations up do the socket overhead, thus I'd say in this setup you +could perhaps save 1% by using sharedmem. +</para> + +</sect2> + +<sect2 id="hard-numbers"> +<title>Some Hard Numbers</title> + +<para> +These are done with the current development snapshot. I also wanted to +try out the real hard cases, so this is not what everyday applications +should use. +</para> + +<para> +I wrote an application called streamsound which sends streaming data to +&arts;. Here it is running with realtime priority (without problems), +and one small serverside (volume-scaling and clipping) plugin: +</para> + +<programlisting> + 4974 stefan 20 0 2360 2360 1784 S 0 17.7 1.8 0:21 artsd + 5016 stefan 20 0 2208 2208 1684 S 0 7.2 1.7 0:02 streamsound + 5002 stefan 20 0 2208 2208 1684 S 0 6.8 1.7 0:07 streamsound + 4997 stefan 20 0 2208 2208 1684 S 0 6.6 1.7 0:07 streamsound +</programlisting> + +<para> +Each of them is streaming with 3 fragments a 1024 bytes (18 ms). There +are three such clients running simultaneously. I know that that does +look a bit too much, but as I said: take a profiler and find out what +costs time, and if you like, improve it. +</para> + +<para> +However, I don't think using streaming like that is realistic or makes +sense. To take it even more to the extreme, I tried what would be the +lowest latency possible. Result: you can do streaming without +interruptions with one client application, if you take 2 fragments of +128 bytes between aRts and the soundcard, and between the client +application and aRts. This means that you have a total maximum latency +of 128*4/44100*4 = 3 ms, where 1.5 ms is generated due to soundcard I/O +and 1.5 ms is generated through communication with &arts;. Both +applications need to run realtimed. +</para> + +<para> +But: this costs an enormous amount of +<acronym>CPU</acronym>. This example cost you about 45% of my +P-II/350. I also starts to click if you start top, move windows on your +X11 display or do disk I/O. All these are kernel issues. The problem is +that scheduling two or more applications with realtime priority cost you +an enormous amount of effort, too, even more if the communicate, notify +each other &etc;. +</para> + +<para> +Finally, a more real life example. This is &arts; with artsd and one +artscat (one streaming client) running 16 fragments a 4096 bytes: +</para> + +<programlisting> + 5548 stefan 12 0 2364 2364 1752 R 0 4.9 1.8 0:03 artsd + 5554 stefan 3 0 752 752 572 R 0 0.7 0.5 0:00 top + 5550 stefan 2 0 2280 2280 1696 S 0 0.5 1.7 0:00 artscat +</programlisting> + +</sect2> +</sect1> + +<!-- TODO + +<sect1 id="dynamic-instantiation"> +<title>Dynamic Instantiation</title> +<para> +</para> +</sect1> + +--> + +<sect1 id="busses"> +<title>Busses</title> + +<para> +Busses are dynamically built connections that transfer audio. Basically, +there are some uplinks and some downlinks. All signals from the uplinks +are added and send to the downlinks. +</para> + +<para> +Busses as currently implemented operate in stereo, so you can only +transfer stereo data over busses. If you want mono data, well, transfer +it only over one channel and set the other to zero or whatever. What +you need to to, is to create one or more Synth_BUS_UPLINK +objects and tell them a bus name, to which they should talk (⪚ +<quote>audio</quote> or <quote>drums</quote>). Simply throw the data in +there. +</para> + +<para> +Then, you'll need to create one or more Synth_BUS_DOWNLINK +objects, and tell them the bus name (<quote>audio</quote> or +<quote>drums</quote> ... if it matches, the data will get through), and +the mixed data will come out again. +</para> + +<para> +The uplinks and downlinks can reside in different structures, you can +even have different &arts-builder;s running and start an uplink in one +and receive the data from the other with a downlink. +</para> + +<para> +What is nice about busses is, that they are fully dynamic. Clients can +plug in and out on the fly. There should be no clicking or noise as this +happens. +</para> + +<para> +Of course, you should not plug out a client playing a signal, since it +will probably not be a zero level when plugged out the bus, and then it +will click. +</para> +</sect1> + +<!-- TODO +<sect1 id="network-ransparency"> +<title>Network Transparency</title> +<para> +</para> +</sect1> + +<sect1 id="security"> +<title>Security</title> +<para> +</para> +</sect1> + + +<sect1 id="effects"> +<title>Effects and Effect Stacks</title> +<para> +</para> +</sect1> + +--> +<sect1 id="trader"> +<title>Trader</title> + +<para> +&arts;/&MCOP; heavily relies on splitting up things into small +components. This makes things very flexible, as you can extend the +system easily by adding new components, which implement new effects, +fileformats, oscillators, gui elements, ... As almost everything is a +component, almost everything can be extended easily, without changing +existing sources. New components can be simply loaded dynamically to +enhance already existing applications. +</para> + +<para> +However, to make this work, two things are required: +</para> + +<itemizedlist> + +<listitem> +<para> +Components must advertise themselves - they must describe what great +things they offer, so that applications will be able to use them. +</para> +</listitem> + +<listitem> +<para> +Applications must actively look for components that they could use, +instead of using always the same thing for some task. +</para> +</listitem> + +</itemizedlist> + +<para> +The combination of this: components which say <quote>here I am, I am +cool, use me</quote>, and applications (or if you like, other +components) which go out and look which component they could use to get +a thing done, is called trading. +</para> + +<para> +In &arts;, components describe themselves by specifying values that they +<quote>support</quote> for properties. A typical property for a +file-loading component could be the extension of the files that it can +process. Typical values could be <literal +role="extension">wav</literal>, <literal role="extension">aiff</literal> +or <literal role="extension">mp3</literal>. +</para> + +<para> +In fact, every component may choose to offer many different values for +one property. So one single component could offer reading both, <literal +role="extension">wav</literal> and <literal +role="extension">aiff</literal> files, by specifying that it supports +these values for the property <quote>Extension</quote>. +</para> + +<para> +To do so, a component has to place a <literal +role="extension">.mcopclass</literal> file at an appropriate place, +containing the properties it supports, for our example, this could look +like this (and would be installed in +<filename><replaceable>componentdir</replaceable>/Arts/WavPlayObject.mcopclass</filename>): +</para> + +<programlisting> +Interface=Arts::WavPlayObject,Arts::PlayObject,Arts::SynthModule,Arts::Object +Author="Stefan Westerfeld <stefan@space.twc.de>" +URL="http://www.arts-project.org" +Extension=wav,aiff +MimeType=audio/x-wav,audio/x-aiff +</programlisting> + +<para> +It is important that the filename of the <literal +role="extension">.mcopclass</literal>-file also says what the interface +of the component is called like. The trader doesn't look at the contents +at all, if the file (like here) is called +<filename>Arts/WavPlayObject.mcopclass</filename>, the component +interface is called <interfacename>Arts::WavPlayObject</interfacename> +(modules map to folders). +</para> + +<para> +To look for components, there are two interfaces (which are defined in +<filename>core.idl</filename>, so you have them in every application), +called <interfacename>Arts::TraderQuery</interfacename> and +<interfacename>Arts::TraderOffer</interfacename>. You to go on a +<quote>shopping tour</quote> for components like this: +</para> + +<orderedlist> +<listitem> +<para> +Create a query object: +</para> +<programlisting> + Arts::TraderQuery query; +</programlisting> +</listitem> + +<listitem> +<para> +Specify what you want. As you saw above, components describe themselves +using properties, for which they offer certain values. So specifying +what you want is done by selecting components that support a certain +value for a property. This is done using the supports method of a +TraderQuery: +</para> + +<programlisting> + query.supports("Interface","Arts::PlayObject"); + query.supports("Extension","wav"); +</programlisting> +</listitem> + +<listitem> +<para> +Finally, perform the query using the query method. Then, you'll +(hopefully) get some offers: +</para> + +<programlisting> + vector<Arts::TraderOffer> *offers = query.query(); +</programlisting> +</listitem> + +<listitem> +<para> +Now you can examine what you found. Important is the interfaceName +method of TraderOffer, which will tell you the name of the component, +that matched the query. You can also find out further properties by +getProperty. The following code will simply iterate through all +components, print their interface names (which could be used for +creation), and delete the results of the query again: +</para> +<programlisting> + vector<Arts::TraderOffer>::iterator i; + for(i = offers->begin(); i != offers->end(); i++) + cout << i->interfaceName() << endl; + delete offers; +</programlisting> +</listitem> +</orderedlist> + +<para> +For this kind of trading service to be useful, it is important to +somehow agree on what kinds of properties components should usually +define. It is essential that more or less all components in a certain +area use the same set of properties to describe themselves (and the same +set of values where applicable), so that applications (or other +components) will be able to find them. +</para> + +<para> +Author (type string, optional): This can be used to ultimately let the +world know that you wrote something. You can write anything you like in +here, e-mail address is of course helpful. +</para> + +<para> +Buildable (type boolean, recommended): This indicates whether the +component is usable with <acronym>RAD</acronym> tools (such as +&arts-builder;) which use components by assigning properties and +connecting ports. It is recommended to set this value to true for +almost any signal processing component (such as filters, effects, +oscillators, ...), and for all other things which can be used in +<acronym>RAD</acronym> like fashion, but not for internal stuff like for +instance <interfacename>Arts::InterfaceRepo</interfacename>. +</para> + +<para> +Extension (type string, used where relevant): Everything dealing with +files should consider using this. You should put the lowercase version +of the file extension without the <quote>.</quote> here, so something +like <userinput>wav</userinput> should be fine. +</para> + +<para> +Interface (type string, required): This should include the full list of +(useful) interfaces your components supports, probably including +<interfacename>Arts::Object</interfacename> and if applicable +<interfacename>Arts::SynthModule</interfacename>. +</para> + +<para> +Language (type string, recommended): If you want your component to be +dynamically loaded, you need to specify the language here. Currently, +the only allowed value is <userinput>C++</userinput>, which means the +component was written using the normal C++ <acronym>API</acronym>. If +you do so, you'll also need to set the <quote>Library</quote> property +below. +</para> + +<para> +Library (type string, used where relevant): Components written in C++ +can be dynamically loaded. To do so, you have to compile them into a +dynamically loadable libtool (<literal role="extension">.la</literal>) +module. Here, you can specify the name of the <literal +role="extension">.la</literal>-File that contains your component. +Remember to use REGISTER_IMPLEMENTATION (as always). +</para> + +<para> +MimeType (type string, used where relevant): Everything dealing with +files should consider using this. You should put the lowercase version +of the standard mimetype here, for instance +<userinput>audio/x-wav</userinput>. +</para> + +<para> +&URL; (type string, optional): If you like to let people know where they +can find a new version of the component (or a homepage or anything), you +can do it here. This should be standard &HTTP; or &FTP; &URL;. +</para> + +</sect1> + +<!-- TODO +<sect1 id="midi-synthesis"> +<title><acronym>MIDI</acronym> Synthesis</title> +<para> +</para> +</sect1> + +<sect1 id="instruments"> +<title>Instruments</title> +<para> +</para> +</sect1> + +<sect1 id="session-management"> +<title>Session Management</title> +<para> +</para> +</sect1> + +<sect1 id="full-duplex"> +<title>Full duplex Audio</title> +<para> +</para> +</sect1> +--> + +<sect1 id="namespaces"> +<title>Namespaces in &arts;</title> + +<sect2 id="namespaces-intro"> +<title>Introduction</title> + +<para> +Each namespace declaration corresponds to a <quote>module</quote> +declaration in the &MCOP; &IDL;. +</para> + +<programlisting> +// mcop idl + +module M { + interface A + { + } +}; + +interface B; +</programlisting> + +<para> +In this case, the generated C++ code for the &IDL; snippet would look +like this: +</para> + +<programlisting> +// C++ header + +namespace M { + /* declaration of A_base/A_skel/A_stub and similar */ + class A { // Smartwrapped reference class + /* [...] */ + }; +} + +/* declaration of B_base/B_skel/B_stub and similar */ +class B { + /* [...] */ +}; +</programlisting> + +<para> +So when referring the classes from the above example in your C++ code, +you would have to write <classname>M::A</classname>, but only +B. However, you can of course use <quote>using M</quote> somewhere - +like with any namespace in C++. +</para> + +</sect2> + +<sect2 id="namespaces-how"> +<title>How &arts; uses namespaces</title> + +<para> +There is one global namespace called <quote>Arts</quote>, which all +programs and libraries that belong to &arts; itself use to put their +declarations in. This means, that when writing C++ code that depends on +&arts;, you normally have to prefix every class you use with +<classname>Arts::</classname>, like this: +</para> + +<programlisting> +int main(int argc, char **argv) +{ + Arts::Dispatcher dispatcher; + Arts::SimpleSoundServer server(Arts::Reference("global:Arts_SimpleSoundServer")); + + server.play("/var/foo/somefile.wav"); +</programlisting> + +<para> +The other alternative is to write a using once, like this: +</para> + +<programlisting> +using namespace Arts; + +int main(int argc, char **argv) +{ + Dispatcher dispatcher; + SimpleSoundServer server(Reference("global:Arts_SimpleSoundServer")); + + server.play("/var/foo/somefile.wav"); + [...] +</programlisting> + +<para> +In &IDL; files, you don't exactly have a choice. If you are writing code +that belongs to &arts; itself, you'll have to put it into module &arts;. +</para> + +<programlisting> +// IDL File for aRts code: +#include <artsflow.idl> +module Arts { // put it into the Arts namespace + interface Synth_TWEAK : SynthModule + { + in audio stream invalue; + out audio stream outvalue; + attribute float tweakFactor; + }; +}; +</programlisting> + +<para> +If you write code that doesn't belong to &arts; itself, you should not +put it into the <quote>Arts</quote> namespace. However, you can make an +own namespace if you like. In any case, you'll have to prefix classes +you use from &arts;. +</para> + +<programlisting> +// IDL File for code which doesn't belong to aRts: +#include <artsflow.idl> + +// either write without module declaration, then the generated classes will +// not use a namespace: +interface Synth_TWEAK2 : Arts::SynthModule +{ + in audio stream invalue; + out audio stream outvalue; + attribute float tweakFactor; +}; + +// however, you can also choose your own namespace, if you like, so if you +// write an application "PowerRadio", you could for instance do it like this: +module PowerRadio { + struct Station { + string name; + float frequency; + }; + + interface Tuner : Arts::SynthModule { + attribute Station station; // no need to prefix Station, same module + out audio stream left, right; + }; +}; +</programlisting> + +</sect2> + +<sect2 id="namespaces-implementation"> +<title>Internals: How the Implementation Works</title> + +<para> +Often, in interfaces, casts, method signatures and similar, &MCOP; needs +to refer to names of types or interfaces. These are represented as +string in the common &MCOP; datastructures, while the namespace is +always fully represented in the C++ style. This means the strings would +contain <quote>M::A</quote> and <quote>B</quote>, following the example +above. +</para> + +<para> +Note this even applies if inside the &IDL; text the namespace qualifiers +were not given, since the context made clear which namespace the +interface <interfacename>A</interfacename> was meant to be used in. +</para> + +</sect2> +</sect1> + +<sect1 id="threads"> +<title>Threads in &arts;</title> + +<sect2 id="threads-basics"> +<title>Basics</title> + +<para> +Using threads isn't possible on all platforms. This is why &arts; was +originally written without using threading at all. For almost all +problems, for each threaded solution to the problem, there is a +non-threaded solution that does the same. +</para> + +<para> +For instance, instead of putting audio output in a separate thread, and +make it blocking, &arts; uses non-blocking audio output, and figures out +when to write the next chunk of data using +<function>select()</function>. +</para> + +<para> +However, &arts; (in very recent versions) at least provides support for +people who do want to implement their objects using threads. For +instance, if you already have code for an <literal +role="extension">mp3</literal> player, and the code expects the <literal +role="extension">mp3</literal> decoder to run in a separate thread, it's +usually the easiest thing to do to keep this design. +</para> + +<para> +The &arts;/&MCOP; implementation is built along sharing state between +separate objects in obvious and non-obvious ways. A small list of shared +state includes: +</para> + +<itemizedlist> +<listitem><para> +The Dispatcher object which does &MCOP; communication. +</para> +</listitem> + +<listitem> +<para> +The Reference counting (Smartwrappers). +</para> +</listitem> + +<listitem> +<para> +The IOManager which does timer and fd watches. +</para> +</listitem> + +<listitem> +<para> +The ObjectManager which creates objects and dynamically loads plugins. +</para> +</listitem> + +<listitem> +<para> +The FlowSystem which calls calculateBlock in the appropriate situations. +</para> +</listitem> +</itemizedlist> + +<para> +All of the above objects don't expect to be used concurrently (&ie; +called from separate threads at the same time). Generally there are two +ways of solving this: +</para> + +<itemizedlist> +<listitem> +<para> +Require the caller of any functions on this objects to +acquire a lock before using them. +</para> +</listitem> + +<listitem> +<para> +Making these objects really threadsafe and/or create +per-thread instances of them. +</para> +</listitem> +</itemizedlist> + +<para> +&arts; follows the first approach: you will need a lock whenever you talk to +any of these objects. The second approach is harder to do. A hack which +tries to achieve this is available at +<ulink url="http://space.twc.de/~stefan/kde/download/arts-mt.tar.gz"> +http://space.twc.de/~stefan/kde/download/arts-mt.tar.gz</ulink>, but for +the current point in time, a minimalistic approach will probably work +better, and cause less problems with existing applications. +</para> + +</sect2> +<sect2 id="threads-locking"> +<title>When/how to acquire the lock?</title> + +<para> +You can get/release the lock with the two functions: +</para> + +<itemizedlist> +<listitem> +<para> +<ulink +url="http://space.twc.de/~stefan/kde/arts-mcop-doc/arts-reference/headers/Arts__Dispatcher.html#lock"><function>Arts::Dispatcher::lock()</function></ulink> +</para> +</listitem> +<listitem> +<para> +<ulink +url="http://space.twc.de/~stefan/kde/arts-mcop-doc/arts-reference/headers/Arts__Dispatcher.html#unlock"><function>Arts::Dispatcher::unlock()</function></ulink> +</para> +</listitem> +</itemizedlist> + +<para> +Generally, you don't need to acquire the lock (and you shouldn't try to +do so), if it is already held. A list of conditions when this is the +case is: +</para> + +<itemizedlist> +<listitem> +<para> +You receive a callback from the IOManager (timer or fd). +</para> +</listitem> + +<listitem> +<para> +You get call due to some &MCOP; request. +</para> +</listitem> + +<listitem> +<para> +You are called from the NotificationManager. +</para> +</listitem> + +<listitem> +<para> +You are called from the FlowSystem (calculateBlock) +</para> +</listitem> +</itemizedlist> + +<para> +There are also some exceptions of functions. which you can only call in +the main thread, and for that reason you will never need a lock to call +them: +</para> + +<itemizedlist> +<listitem> +<para> +Constructor/destructor of Dispatcher/IOManager. +</para> +</listitem> + +<listitem> +<para> +<methodname>Dispatcher::run()</methodname> / +<methodname>IOManager::run()</methodname> +</para> +</listitem> + +<listitem> +<para><methodname>IOManager::processOneEvent()</methodname></para> +</listitem> +</itemizedlist> + +<para> +But that is it. For everything else that is somehow related to &arts;, +you will need to get the lock, and release it again when +done. Always. Here is a simple example: +</para> + +<programlisting> +class SuspendTimeThread : Arts::Thread { +public: + void run() { + /* + * you need this lock because: + * - constructing a reference needs a lock (as global: will go to + * the object manager, which might in turn need the GlobalComm + * object to look up where to connect to) + * - assigning a smartwrapper needs a lock + * - constructing an object from reference needs a lock (because it + * might need to connect a server) + */ + Arts::Dispatcher::lock(); + Arts::SoundServer server = Arts::Reference("global:Arts_SoundServer"); + Arts::Dispatcher::unlock(); + + for(;;) { /* + * you need a lock here, because + * - dereferencing a smartwrapper needs a lock (because it might + * do lazy creation) + * - doing an MCOP invocation needs a lock + */ + Arts::Dispatcher::lock(); + long seconds = server.secondsUntilSuspend(); + Arts::Dispatcher::unlock(); + + printf("seconds until suspend = %d",seconds); + sleep(1); + } + } +} +</programlisting> + + +</sect2> + +<sect2 id="threads-classes"> +<title>Threading related classes</title> + +<para> +The following threading related classes are currently available: +</para> + +<itemizedlist> +<listitem> +<para> +<ulink +url="http://www.arts-project.org/doc/headers/Arts__Thread.html"><classname> +Arts::Thread</classname></ulink> - which encapsulates a thread. +</para> +</listitem> + +<listitem> +<para> +<ulink url="http://www.arts-project.org/doc/headers/Arts__Mutex.html"> +<classname>Arts::Mutex</classname></ulink> - which encapsulates a mutex. +</para> +</listitem> + +<listitem> +<para> +<ulink +url="http://www.arts-project.org/doc/headers/Arts__ThreadCondition.html"> +<classname>Arts::ThreadCondition</classname></ulink> - which provides +support to wake up threads which are waiting for a certain condition to +become true. +</para> +</listitem> + +<listitem> +<para> +<ulink +url="http://www.arts-project.org/doc/headers/Arts__SystemThreads.html"><classname>Arts::SystemThreads</classname></ulink> +- which encapsulates the operating system threading layer (which offers +a few helpful functions to application programmers). +</para> +</listitem> +</itemizedlist> + +<para> +See the links for documentation. +</para> + +</sect2> +</sect1> + +<sect1 id="references-errors"> +<title>References and Error Handling</title> + +<para> +&MCOP; references are one of the most central concepts in &MCOP; +programming. This section will try to describe how exactly references +are used, and will especially also try to cover cases of failure (server +crashes). +</para> + +<sect2 id="references-properties"> +<title>Basic properties of references</title> + +<itemizedlist> +<listitem> +<para> +An &MCOP; reference is not an object, but a reference to an object: Even +though the following declaration + +<programlisting> + Arts::Synth_PLAY p; +</programlisting> + +looks like a definition of an object, it only declares a reference to an +object. As C++ programmer, you might also think of it as Synth_PLAY *, a +kind of pointer to a Synth_PLAY object. This especially means, that p +can be the same thing as a NULL pointer. +</para> +</listitem> + +<listitem> +<para> +You can create a NULL reference by assigning it explicitly +</para> +<programlisting> + Arts::Synth_PLAY p = Arts::Synth_PLAY::null(); +</programlisting> +</listitem> + +<listitem> +<para> +Invoking things on a NULL reference leads to a core dump +</para> +<programlisting> + Arts::Synth_PLAY p = Arts::Synth_PLAY::null(); + string s = p.toString(); +</programlisting> +<para> +will lead to a core dump. Comparing this to a pointer, it is essentially +the same as +<programlisting> + QWindow* w = 0; + w->show(); +</programlisting> +which every C++ programmer would know to avoid. +</para> +</listitem> + +<listitem> +<para> +Uninitialized objects try to lazy-create themselves upon first use +</para> + +<programlisting> + Arts::Synth_PLAY p; + string s = p.toString(); +</programlisting> +<para> +is something different than dereferencing a NULL pointer. You didn't tell +the object at all what it is, and now you try to use it. The guess here +is that you want to have a new local instance of a Arts::Synth_PLAY +object. Of course you might have wanted something else (like creating the +object somewhere else, or using an existing remote object). However, it +is a convenient short cut to creating objects. Lazy creation will not work +once you assigned something else (like a null reference). +</para> + +<para> +The equivalent C++ terms would be +<programlisting> + QWidget* w; + w->show(); +</programlisting> + +which obviously in C++ just plain segfaults. So this is different here. +This lazy creation is tricky especially as not necessarily an implementation +exists for your interface. +</para> + +<para> +For instance, consider an abstract thing like a +Arts::PlayObject. There are certainly concrete PlayObjects like those for +playing mp3s or wavs, but + +<programlisting> + Arts::PlayObject po; + po.play(); +</programlisting> + +will certainly fail. The problem is that although lazy creation kicks +in, and tries to create a PlayObject, it fails, because there are only +things like Arts::WavPlayObject and similar. Thus, use lazy creation +only when you are sure that an implementation exists. +</para> +</listitem> + +<listitem> +<para> +References may point to the same object +</para> + +<programlisting> + Arts::SimpleSoundServer s = Arts::Reference("global:Arts_SimpleSoundServer"); + Arts::SimpleSoundServer s2 = s; +</programlisting> + +<para> +creates two references referring to the same object. It doesn't copy any +value, and doesn't create two objects. +</para> +</listitem> + +<listitem> +<para> +All objects are reference counted So once an object isn't referred any +longer by any references, it gets deleted. There is no way to +explicitly delete an object, however, you can use something like this +<programlisting> + Arts::Synth_PLAY p; + p.start(); + [...] + p = Arts::Synth_PLAY::null(); +</programlisting> +to make the Synth_PLAY object go away in the end. Especially, it should never +be necessary to use new and delete in conjunction with references. +</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="references-failure"> +<title>The case of failure</title> + +<para> +As references can point to remote objects, the servers containing these +objects can crash. What happens then? +</para> + +<itemizedlist> + +<listitem> +<para> +A crash doesn't change whether a reference is a null reference. This +means that if <function>foo.isNull()</function> was +<returnvalue>true</returnvalue> before a server crash then it is also +<returnvalue>true</returnvalue> after a server crash (which is +clear). It also means that if <function>foo.isNull()</function> was +<returnvalue>false</returnvalue> before a server crash (foo referred to +an object) then it is also <returnvalue>false</returnvalue> after the +server crash. +</para> +</listitem> + +<listitem> +<para> +Invoking methods on a valid reference stays safe +Suppose the server containing the object calc crashed. Still calling things +like +<programlisting> + int k = calc.subtract(i,j) +</programlisting> +are safe. Obviously subtract has to return something here, which it +can't because the remote object no longer exists. In this case (k == 0) +would be true. Generally, operations try to return something +<quote>neutral</quote> as result, such as 0.0, a null reference for +objects or empty strings, when the object no longer exists. +</para> +</listitem> + +<listitem> +<para> +Checking <function>error()</function> reveals whether something worked. +</para> + +<para> +In the above case, +<programlisting> + int k = calc.subtract(i,j) + if(k.error()) { + printf("k is not i-j!\n"); + } +</programlisting> +would print out <computeroutput>k is not i-j</computeroutput> whenever +the remote invocation didn't work. Otherwise <varname>k</varname> is +really the result of the subtract operation as performed by the remote +object (no server crash). However, for methods doing things like +deleting a file, you can't know for sure whether it really happened. Of +course it happened if <function>.error()</function> is +<returnvalue>false</returnvalue>. However, if +<function>.error()</function> is <returnvalue>true</returnvalue>, there +are two possibilities: +</para> + +<itemizedlist> +<listitem> +<para> +The file got deleted, and the server crashed just after deleting it, but +before transferring the result. +</para> +</listitem> + +<listitem> +<para> +The server crashed before being able to delete the file. +</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para> +Using nested invocations is dangerous in crash resistant programs +</para> + +<para> +Using something like +<programlisting> + window.titlebar().setTitle("foo"); +</programlisting> +is not a good idea. Suppose you know that window contains a valid Window +reference. Suppose you know that <function>window.titlebar()</function> +will return a Titlebar reference because the Window object is +implemented properly. However, still the above statement isn't safe. +</para> + +<para> +What could happen is that the server containing the Window object has +crashed. Then, regardless of how good the Window implementation is, you +will get a null reference as result of the window.titlebar() +operation. And then of course invoking setTitle on that null reference +will lead to a crash as well. +</para> + +<para> +So a safe variant of this would be +<programlisting> + Titlebar titlebar = window.titlebar(); + if(!window.error()) + titlebar.setTitle("foo"); +</programlisting> +add the appropriate error handling if you like. If you don't trust the +Window implementation, you might as well use +<programlisting> + Titlebar titlebar = window.titlebar(); + if(!titlebar.isNull()) + titlebar.setTitle("foo"); +</programlisting> +which are both safe. +</para> +</listitem> +</itemizedlist> + +<para> +There are other conditions of failure, such as network disconnection +(suppose you remove the cable between your server and client while your +application runs). However their effect is the same like a server crash. +</para> + +<para> +Overall, it is of course a consideration of policy how strictly you try +to trap communication errors throughout your application. You might +follow the <quote>if the server crashes, we need to debug the server +until it never crashes again</quote> method, which would mean you need +not bother about all these problems. +</para> + +</sect2> + +<sect2 id="references-internals"> +<title>Internals: Distributed Reference Counting</title> + +<para> +An object, to exist, must be owned by someone. If it isn't, it will +cease to exist (more or less) immediately. Internally, ownership is +indicated by calling <function>_copy()</function>, which increments an +reference count, and given back by calling +<function>_release()</function>. As soon as the reference count drops to +zero, a delete will be done. +</para> + +<para> +As a variation of the theme, remote usage is indicated by +<function>_useRemote()</function>, and dissolved by +<function>_releaseRemote()</function>. These functions lead a list which +server has invoked them (and thus owns the object). This is used in case +this server disconnects (&ie; crash, network failure), to remove the +references that are still on the objects. This is done in +<function>_disconnectRemote()</function>. +</para> + +<para> +Now there is one problem. Consider a return value. Usually, the return +value object will not be owned by the calling function any longer. It +will however also not be owned by the caller, until the message holding +the object is received. So there is a time of +<quote>ownershipless</quote> objects. +</para> + +<para> +Now, when sending an object, one can be reasonable sure that as soon as +it is received, it will be owned by somebody again, unless, again, the +receiver dies. However this means that special care needs to be taken +about object at least while sending, probably also while receiving, so +that it doesn't die at once. +</para> + +<para> +The way &MCOP; does this is by <quote>tagging</quote> objects that are +in process of being copied across the wire. Before such a copy is +started, <function>_copyRemote</function> is called. This prevents the +object from being freed for a while (5 seconds). Once the receiver calls +<function>_useRemote()</function>, the tag is removed again. So all +objects that are send over wire are tagged before transfer. +</para> + +<para> +If the receiver receives an object which is on his server, of course he +will not <function>_useRemote()</function> it. For this special case, +<function>_cancelCopyRemote()</function> exists to remove the tag +manually. Other than that, there is also timer based tag removal, if +tagging was done, but the receiver didn't really get the object (due to +crash, network failure). This is done by the +<classname>ReferenceClean</classname> class. +</para> + +</sect2> + +</sect1> + +<sect1 id="detail-gui-elements"> +<title>&GUI; Elements</title> + +<para> +&GUI; elements are currently in the experimental state. However, this +section will describe what is supposed to happen here, so if you are a +developer, you will be able to understand how &arts; will deal with +&GUI;s in the future. There is some code there already, too. +</para> + +<para> +&GUI; elements should be used to allow synthesis structures to interact +with the user. In the simplest case, the user should be able to modify +some parameters of a structure directly (such as a gain factor which is +used before the final play module). +</para> + +<para> +In more complex settings, one could imagine the user modifying +parameters of groups of structures and/or not yet running structures, +such as modifying the <acronym>ADSR</acronym> envelope of the currently +active &MIDI; instrument. Another thing would be setting the filename of +some sample based instrument. +</para> + +<para> +On the other hand, the user could like to monitor what the synthesizer +is doing. There could be oscilloscopes, spectrum analyzers, volume +meters and <quote>experiments</quote> that figure out the frequency +transfer curve of some given filter module. +</para> + +<para> +Finally, the &GUI; elements should be able to control the whole +structure of what is running inside &arts; and how. The user should be +able to assign instruments to midi channels, start new effect +processors, configure his main mixer desk (which is built of &arts; +structures itself) to have one channel more and use another strategy for +its equalizers. +</para> + +<para> +You see - the <acronym>GUI</acronym> elements should bring all +possibilities of the virtual studio &arts; should simulate to the +user. Of course, they should also gracefully interact with midi inputs +(such as sliders should move if they get &MIDI; inputs which also change +just that parameter), and probably even generate events themselves, to +allow the user interaction to be recorded via sequencer. +</para> + +<para> +Technically, the idea is to have an &IDL; base class for all widgets +(<classname>Arts::Widget</classname>), and derive a number of commonly +used widgets from there (like <classname>Arts::Poti</classname>, +<classname>Arts::Panel</classname>, <classname>Arts::Window</classname>, +...). +</para> + +<para> +Then, one can implement these widgets using a toolkit, for instance &Qt; +or Gtk. Finally, effects should build their &GUI;s out of existing +widgets. For instance, a freeverb effect could build it's &GUI; out of +five <classname>Arts::Poti</classname> thingies and an +<classname>Arts::Window</classname>. So IF there is a &Qt; +implementation for these base widgets, the effect will be able to +display itself using &Qt;. If there is Gtk implementation, it will also +work for Gtk (and more or less look/work the same). +</para> + +<para> +Finally, as we're using &IDL; here, &arts-builder; (or other tools) will +be able to plug &GUI;s together visually, or autogenerate &GUI;s given +hints for parameters, only based on the interfaces. It should be +relatively straight forward to write a <quote>create &GUI; from +description</quote> class, which takes a &GUI; description (containing +the various parameters and widgets), and creates a living &GUI; object +out of it. +</para> + +<para> +Based on &IDL; and the &arts;/&MCOP; component model, it should be easy +to extend the possible objects which can be used for the &GUI; just as +easy as it is to add a plugin implementing a new filter to &arts;. +</para> + +</sect1> + +</chapter> diff --git a/doc/artsbuilder/digitalaudio.docbook b/doc/artsbuilder/digitalaudio.docbook new file mode 100644 index 00000000..99d24968 --- /dev/null +++ b/doc/artsbuilder/digitalaudio.docbook @@ -0,0 +1,14 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE appendix PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<appendix id="intro-digital-audio"> +<title>Introduction to Digital Audio</title> + +<para>digital sampling, filters, effects, &etc;</para> + +</appendix> + + + diff --git a/doc/artsbuilder/faq.docbook b/doc/artsbuilder/faq.docbook new file mode 100644 index 00000000..c5b111ec --- /dev/null +++ b/doc/artsbuilder/faq.docbook @@ -0,0 +1,1112 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> +<chapter id="faq"> +<title>Questions and answers</title> + +<para> +This section answers some frequently asked questions about &arts;. +</para> + +<qandaset id="faq-general"> +<title>General Questions</title> + +<qandaentry> +<question> +<para> +Does &kde; support my sound card for audio output? +</para> +</question> + +<answer> +<para> +&kde; uses &arts; to play sound, and &arts; uses the &Linux; kernel +sound drivers, either <acronym>OSS</acronym> or <acronym>ALSA</acronym> +(using <acronym>OSS</acronym> emulation). If your sound card is +supported by either <acronym>ALSA</acronym> or <acronym>OSS</acronym> +and properly configured (&ie; any other &Linux; application can output +sound), it will work. There are however some problems with some specific +hardware, please read the <link linkend="faq-hardware-specific">section +for hardware specific problems</link> if you're having problems with artsd +on your machine. +</para> +<para> +Meanwhile also support for various other platforms has been added. Here is +a complete list of how the most recent version of &arts; can play sound. If +you have an unsupported platform, please consider porting &arts; to your +platform. +</para> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> +<entry>&arts; audio I/O method</entry> +<entry>Comment</entry> +</row> +</thead> + +<tbody> +<row> +<entry>paud</entry> +<entry>Support for AIX Personal Audio Device</entry> +</row> + +<row> +<entry>alsa</entry> +<entry>Linux ALSA-0.5 and ALSA-0.9 drivers</entry> +</row> + +<row> +<entry>libaudioio</entry> +<entry>Support for generic LibAudioIO library which works on Solaris</entry> +</row> + +<row> +<entry>nas</entry> +<entry>NAS sound server, useful for X Terminals with NAS support</entry> +</row> + +<row> +<entry>null</entry> +<entry>Null audio device, discards sound silently</entry> +</row> + +<row> +<entry>oss</entry> +<entry>OSS (Open Sound System) support (works on Linux, various BSDs and + other platforms with OSS drivers installed)</entry> +</row> + +<row> +<entry>toss</entry> +<entry>Threaded OSS support, which works better in some cases where the + standard OSS support doesn't work well</entry> +</row> + +<row> +<entry>sgi</entry> +<entry>SGI Direct Media support for IRIX</entry> +</row> + +<row> +<entry>sun</entry> +<entry>Solaris support</entry> +</row> + +</tbody> +</tgroup> +</informaltable> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I can't play <literal role="extension">wav</literal> files with &artsd;! +</para> +</question> + +<answer> +<para> +Check that &artsd; is linked to <filename>libaudiofile</filename> +(<userinput><command>ldd</command> +<parameter>artsd</parameter></userinput>). If it isn't, download +kdesupport, recompile everything, and it will work. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I hear sound when logged in as <systemitem +class="username">root</systemitem> but no other users have sound! +</para> +</question> + +<answer> +<para> +The permissions of the file <filename +class="devicefile">/dev/dsp</filename> affect which users will have +sound. To allow everyone to use it, do this: +</para> + +<procedure> +<step> +<para> +Log in as <systemitem class="username">root</systemitem>. +</para> +</step> + +<step> +<para> +Open a &konqueror; window. +</para> +</step> + +<step> +<para> +Go into the <filename class="directory">/dev</filename> folder. +</para> +</step> + +<step> +<para> +Click on the file <filename>dsp</filename> with the +<mousebutton>right</mousebutton> mouse button, and choose properties. +</para> +</step> + +<step> +<para> +Click on the <guilabel>Permissions</guilabel> tab. +</para> +</step> + +<step> +<para> +Check the <guilabel>Read</guilabel> and <guilabel>Write</guilabel> check +boxes in all sections. +</para> +</step> + +<step> +<para> +Click on <guibutton>OK</guibutton>. +</para> +</step> +</procedure> + +<para> +You can achieve the same effect in a terminal window using the command +<userinput><command>chmod</command> <option>666</option> +<parameter>/dev/dsp</parameter></userinput>. +</para> + +<para> +For restricting access to sound to specific users, you can use group +permissions. On some &Linux; distributions, for instance Debian/Potato, +<filename class="devicefile">/dev/dsp</filename> is already owned by a +group called <systemitem class="groupname">audio</systemitem>, so all +you need to do is add the users to this group. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +This helps for &artsd;, but what about &kmix;, &kmid;, &kscd;,&etc;? +</para> +</question> +<answer> + +<para> +There are various other devices which provide functionality accessed by +multimedia applications. You can treat them in the same way, either by +making them accessible for everyone, or using groups to control +access. Here is a list, which may still be incomplete (also if there are +various devices in a form like <filename +class="devicefile">midi0</filename>, <filename +class="devicefile">midi1</filename>, ..., then only the 0-version is +listed here): +</para> + +<itemizedlist> +<listitem> +<para> +<filename class="devicefile">/dev/admmidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/adsp0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/amidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/amixer0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/audio</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/audio0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/cdrom</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/dmfm0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/dmmidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/dsp</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/dsp0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/midi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/midi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/midi00</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/midi00</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/mixer</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/mixer0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/mpu401data</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/mpu401stat</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/music</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/rmidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/rtc</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/sequencer</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/smpte0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile">/dev/sndstat</filename> +</para> +</listitem> +</itemizedlist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What can I do if artsd doesn't start or crashes while running?</para> +</question> + +<answer> +<para> +First of all: try using the default settings in &kcontrol; (or if you +are starting manually, don't give additional options besides maybe +<userinput><option>-F</option><parameter>10</parameter> +<option>-S</option><parameter>4096</parameter></userinput> for +latency). Especially <emphasis>full duplex is likely to break</emphasis> +with various drivers, so try disabling it. +</para> + +<para> +A good way to figure out why &artsd; doesn't start (or crashes while +running) is to start it manually. Open a &konsole; window, and do: +</para> + +<screen width="40"><prompt>%</prompt> <userinput><command>artsd</command> <option>-F</option><parameter>10</parameter> <option>-S</option><parameter>4096</parameter></userinput></screen> + +<para> +You can also add the <option>-l0</option> option, which will print more +information about what is happening, like this: +</para> +<screen width="40"><prompt>%</prompt> <userinput><command>artsd</command> <option>-l0</option> <option>-F</option><parameter>10</parameter> <option>-S</option><parameter>4096</parameter></userinput></screen> + +<para> +Doing so, you will probably get some useful information why it didn't +start. Or, if it crashes when doing this-and-that, you can do +this-and-that, and see <quote>how</quote> it crashes. If you want to +report a bug, producing a backtrace with <command>gdb</command> and/or +an <command>strace</command> may help finding the problem. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can I relocate &artsd; (move compiled files to another +folder)?</para> +</question> + +<answer> +<para> +You can't relocate &arts; perfectly. The problem is that &artswrapper; +has the location of &artsd; compiled in due to security reasons. You can +however use the <filename>.mcoprc</filename> file +(TraderPath/ExtensionPath entries) to at least make a relocated &artsd; +find it's components. See the <link linkend="the-mcoprc-file">chapter +about the <filename>.mcoprc</filename> file</link> for details on how to +do this. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can I compile &arts; with gcc-3.0?</para> +</question> + +<answer> +<para> +Short answer: no, &arts; will not work if you compile it with gcc-3.0. +</para> + +<para> +Long answer: In the official release, there are two gcc-3.0 bugs which affect +&arts;. The first, gcc-3.0 bug c++/2733 is relatively harmless (and has to do +with problems with the asm statement). It breaks compilation of convert.cc. It +has been fixed in the gcc-3.0 CVS, and will no longer be a problem with +gcc-3.0.1 and higher. A workaround has also been added to the CVS version +of KDE/aRts. +</para> +<para> +The second gcc-3.0 bug, c++/3145 (which is generation of wrong code for some +cases of multiple virtual inheritance) is critical. Applications like &artsd; +will simply crash on startup when compiled with gcc-3.0. Even if some progress +has been made in the gcc-3.0 branch at time of this writing, still &artsd; +crashes quite often, unpredictably. +</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>What applications run under &arts;?</para> +</question> +<answer> + +<para> +Obviously, all of the applications included with &kde; are +&arts;-aware. This includes: +</para> + +<itemizedlist> +<listitem><para>&noatun;</para></listitem> +<listitem><para>&arts-builder;</para></listitem> +<listitem><para>&aktion;</para></listitem> +<listitem><para>&kmid;</para></listitem> +<listitem><para>&kmidi;</para></listitem> +<listitem><para>&kmix;</para></listitem> +<listitem><para>&kscd;</para></listitem> +<listitem><para>&kde; games such as &kpoker; and +&ktuberling;</para></listitem> +</itemizedlist> + +<para> +Some &kde; applications that are not yet included in the &kde; release +(⪚ in kdenonbeta) also support &arts;, including: +</para> + +<itemizedlist> +<listitem><para>&brahms;</para></listitem> +<listitem><para><application>Kaboodle</application></para></listitem> +<listitem><para><application>Kdao</application></para></listitem> +</itemizedlist> + +<para> +The following non-&kde; applications are known to work with &arts;: +</para> + +<itemizedlist> +<listitem><para><application>xmms</application> (with &arts; +plug-in)</para></listitem> +<listitem><para>Real Networks <application>RealPlayer</application> 8.0 +(works with &artsdsp;; native &arts; support is being +considered)</para></listitem> +</itemizedlist> + +<para> +The following applications are known <emphasis>not</emphasis> to work +with &arts;: +</para> + +<itemizedlist> +<listitem><para>none</para></listitem> +</itemizedlist> + +<para> +See also the answers to the questions in the section on +<link linkend="faq-non-arts">non-&arts; applications</link>. +</para> + +<para> +This section is incomplete -- if you have more information on supported +and unsupported applications, please send them to the author so they can +be included here. +</para> +</answer> +</qandaentry> + +</qandaset> + +<qandaset id="faq-non-arts"> +<title>Non-&arts; Applications</title> + +<qandaentry> +<question> +<para> +As soon as &kde; is running, no other application can access my sound device! +</para> +</question> +<answer> +<para> +Since the &arts; sound server used by &kde; is running, it is using the +sound device. If the server is idle for 60 seconds, it will +auto-suspend and release it automatically. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +You said it suspends after 60 seconds, it doesn't for me! +</para> +</question> +<answer> +<para> +If you start artsd from the KDE control panel, the default is to suspend +after 60 seconds. If you start artsd from the command line you need to +use the -s option to specify the autosuspend time, otherwise it will +default to disabling the autosuspend feature. +</para> +<para> +Currently it doesn't suspend when using full duplex. Turn full duplex +off from the &kcontrol; and it will suspend. Disabling full duplex is +generally a good idea anyway if you only use &arts; for playing audio +and not recording. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +How can I run old, non-&arts; applications? +</para> +</question> + +<answer> +<para> +Run them using the &artsdsp;. For instance, if you normally would run: +</para> + +<screen><prompt>%</prompt> <userinput><command>mpg123</command> <option>foo.mp3</option></userinput></screen> + +<para>instead use:</para> + +<screen><prompt>%</prompt> <userinput><command>artsdsp</command> <option>mpg123 foo.mp3</option></userinput></screen> + +<para> +This will redirect the sound output to &arts;. This method doesn't +require changes to the applications. It is something of an ugly hack +however, and does not yet fully support all features of the sound card +device, so some applications may not work. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I can't run &artsdsp; with any application, it always crashes! +</para> +</question> +<answer> +<para> +You need a recent version of the glibc library; &artsdsp; will not work +reliably on some older &Linux; distributions. For instance, on Debian +2.1 (which is glibc 2.0 based) it doesn't work, while on Debian 2.2 +(which is glibc 2.1.3 based), it does. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Are there theoretical limitations with some applications that will +prevent them from ever working with &artsdsp;? +</para> +</question> +<answer> +<para> +No. Using &artsdsp; can result in slightly more latency and +<acronym>CPU</acronym> usage that using the &arts; +<acronym>API</acronym>s directly. Other than that, any application that +doesn't work should be considered a bug in &artsdsp;. The technique used +by &artsdsp; should, if implemented properly, allow +<emphasis>every</emphasis> application to work with it (including large +applications like <application>Quake</application> 3). +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +What can I do if an application doesn't work with &artsdsp;? +</para> +</question> +<answer> +<para> +You can wait for &artsd; to suspend or use the command +<userinput><command>artsshell</command> +<option>suspend</option></userinput> to ask the server to suspend +itself. You will only be able to suspend the server if no &arts; +applications are currently using it, and no &arts; applications will be +able to run when the server is suspended. +</para> + +<para> +If the server is busy, a crude but effective way to get rid of it is: +</para> + + +<screen><prompt>%</prompt> <userinput><command>killall</command> <option>artsd</option> ; <command>killall</command> <option>artswrapper</option></userinput> +<lineannotation>Now start your own application.</lineannotation> +<prompt>%</prompt> <userinput><command>kcminit</command> <option>arts</option></userinput> +</screen> + +<para> +Any currently running &arts; applications may crash, however, once you +kill the server. +</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para> +What about applications written for &kde; 1.x? +</para> +</question> +<answer> +<para> +If you are running &kde; 1.x applications, which output sound via the +&kde; 1 audio server, you will need to run +<application>kaudioserver</application> to make it work. You can start +<application>kaudioserver</application> in the same way than other +non-&arts;-applications: +</para> + +<screen> +<prompt>%</prompt> <userinput><command>artsdsp</command> <option>kaudioserver</option></userinput> +</screen> + +<para> +You will need to have installed kaudioserver (from the same source where +you got your &kde; 1.x applications from) - it belongs to &kde; 1.x, not +&kde; 2. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +What about applications using the enlightened sound daemon, +<acronym>ESD</acronym>? +</para> +</question> +<answer> +<para> +The issue is similar than with +<application>kaudioserver</application>. Such applications will need a +running esd server. You can start <command>esd</command> via &artsdsp;, +and every <acronym>ESD</acronym> aware application should work fine, +like this: +</para> +<screen> +<prompt>%</prompt> <userinput><command>artsdsp</command> <option>esd</option></userinput> +</screen> +<para> +Newer versions of aRts (>= 1.2.0) also can also use the enlightened sound +daemon instead of directly accessing the soundcard. On the command line, you +can use the -a option, such as +</para> +<screen> +<prompt>%</prompt> <userinput><command>artsd</command> <option>-a esd</option></userinput> +</screen> +<para> +to get EsounD support, whereas in KDE, you can use kcontrol to configure artsd +to use esd via Sound -> Sound Server -> Sound I/O. +</para> +</answer> +</qandaentry> + +</qandaset> + +<qandaset id="faq-latency"> +<title>Latency</title> + +<qandaentry> +<question> +<para> +I sometimes hear short pauses when listening to music, is this a bug? +</para> +</question> +<answer> +<para> +This is most likely not a bug, but caused by the fact that the &Linux; +kernel is not very good at real-time scheduling. There are situations +where &arts; will not be able to keep up with playback. You can, +however, enable real-time rights (via &kcontrol;), and use a large +latency setting (like <guilabel>250ms</guilabel> or <guilabel>don't +care</guilabel>), which should improve the situation. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +What's the effect of the response time setting? +</para> +</question> +<answer> +<para> +The help text for this setting in the &kcontrol; can be misleading. A +lower value means that &arts; will take less time to respond to external +events (&ie;. the time that it takes between closing a window and +hearing a sound played by &artsd;). It will also use more +<acronym>CPU</acronym> resources, and be more likely to cause +dropouts.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Is there anything else I can do to prevent pauses? +</para> +</question> +<answer> +<para> +For users of <acronym>IDE</acronym> drives, you can use the +<command>hdparm</command> command to put your <acronym>IDE</acronym> +drive in <acronym>DMA</acronym> mode. A word of warning: this does not +work on all hardware, and can result in having to do a hard reset or in +rare cases, data loss. Read the documentation for the +<command>hdparm</command> command for more details. I have successfully +used the following command: +</para> + +<screen> +<prompt>%</prompt> <userinput><command>hdparm</command> <option>-c1</option> <option>-d1</option> <option>-k1</option> <option>-K1</option> <parameter>/dev/hda</parameter></userinput> +</screen> + +<para> +You need to run this after every boot, so you might want to place it in +a system startup script (how to do this distribution specific, on Debian +&Linux; it is usually put in <filename>/etc/rc.boot</filename>). +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Realtime priority doesn't seem to have any effect for me? +</para> +</question> +<answer> +<para> +Verify that artswrapper is really installed suid <systemitem class="username">root</systemitem>, like it is supposed to +be. A lot of distributions (SuSE7.x for instance) don't do this. You can verify +this using: ls -l $(which artswrapper). Good: +<screen> +<prompt>%</prompt> <userinput><command>ls</command> <option>-l</option> <parameter>$(which artswrapper)</parameter></userinput> +-rwsr-xr-x 1 root root 4556 Sep 24 18:05 /opt/kde2/bin/artswrapper +</screen> +Bad: +<screen> +<prompt>%</prompt> <userinput><command>ls</command> <option>-l</option> <parameter>$(which artswrapper)</parameter></userinput> +-rwxr-xr-x 1 root root 4556 Sep 24 18:05 /opt/kde2/bin/artswrapper +</screen> +If you are not having the s, you can get it using: +<screen> +<prompt>%</prompt> <userinput><command>chown</command> <option>root</option> <parameter>$(which artswrapper)</parameter></userinput> +<prompt>%</prompt> <userinput><command>chmod</command> <option>4755</option> <parameter>$(which artswrapper)</parameter></userinput> +</screen> +</para> + +<para>If you make &artswrapper; SUID <systemitem +class="username">root</systemitem>, it will likely improve the quality +of your audio playback by reducing gaps in the music. However, it +also increases the risk that a bug in the code or a malicious user can +crash or otherwise harm your machine. In addition, on multi-user +machines, prioritizing high-quality audio may result in deteriorated +performance for the users who are trying to make +<quote>productive</quote> use of the machine.</para> + +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para> +Why is &artsd; taking so much <acronym>CPU</acronym> time? +</para> +</question> +<answer> +<para> +Check your response time settings. However, the current version is not +yet really optimized. This will improve, and until then no real +prediction can be made how fast &artsd; can or can't be. +</para> +</answer> +</qandaentry> +</qandaset> + +<qandaset id="faq-network"> +<title>Network Transparency</title> + +<qandaentry> +<question> +<para> +What do I need for network transparency? +</para> +</question> +<answer> +<para> +Enable it in the &kcontrol; <guilabel>Sound Server</guilabel> settings +(<guilabel>enable X11 server for security information</guilabel> and +<guilabel>network transparency</guilabel>). Then copy your +<filename>.mcoprc</filename> to all machines you plan to use network +transparency from. Log in again. Make sure that the hosts that interact +know each other by name (&ie; they have resolvable names or are in +<filename>/etc/hosts</filename>). +</para> + +<para> +This should be all you need to do. However, if it still doesn't work +here are some additional details. The &arts; sound server process, +&artsd;, should only run on one host, the one with the sound card where +the sound should be played. It can be started automatically on login by +&kde; (if you configure that in &kcontrol;), or manually using something +like: +</para> + +<screen> +<prompt>%</prompt> <userinput><command>artsd</command> <option>-n</option> <option>-F</option> <parameter>5</parameter> <option>-S</option> <parameter>8192</parameter></userinput> +</screen> + +<para> +The <option>-n</option> parameter is for network transparency, while the +others configure latency. +</para> + +<para> +Your <filename>.mcoprc</filename> file should have this entry: +</para> + +<screen> +<userinput>GlobalComm=Arts::X11GlobalComm</userinput> +</screen> + +<para> +on all machines involved, in order for network transparency to work, +This is what is enabled by the <guilabel>X11 server for security +information</guilabel> control panel setting. +</para> + +<para> +Finally, in any &kde; version in the 2.0.x series, there is a bug which +applies if you don't have a domain name set. Clients of &artsd; try to +find where to connect to via the <systemitem +class="systemname"><replaceable>hostname</replaceable>.<replaceable>domainname</replaceable></systemitem> +combination. If your domain name is empty, it will try to connect to +<systemitem +class="systemname"><replaceable>hostname</replaceable></systemitem>. (note +the extra dot). Adding an entry like this to +<filename>/etc/hosts</filename> (&ie; <userinput>orion.</userinput> if +your hostname is <systemitem class="systemname">orion</systemitem>) +works around the problem. +</para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para> +How do I debug network transparency if it doesn't work? +</para> +</question> +<answer> +<para> +Assuming you have the &kde; source code, go to <filename +class="directory">kdelibs/arts/examples</filename>, and run +<userinput><command>make</command> <option>check</option></userinput> to +compile some programs, including +<application>referenceinfo</application>. Then run +</para> + +<screen> +<prompt>%</prompt> <userinput><command>./referenceinfo</command> <option>global:Arts_SimpleSoundServer</option></userinput> +</screen> + +<para> +The output will indicate the host name and port being used by +&arts;. For example, <computeroutput>tcp:orion:1698</computeroutput> +would mean that any client trying to use network transparency should +know how to reach host <systemitem +class="systemname">orion</systemitem>. +</para> +</answer> +</qandaentry> + +</qandaset> + +<qandaset id="faq-hardware-specific"> +<title>Hardware specific questions</title> + +<qandaentry> +<question> +<para> +What hardware artsd doesn't work well with? +</para> +</question> +<answer> +<para> +It seems that there are a few linux drivers which don't work well with aRts in +some kernel versions. Please read this list before reporting a bug. If you +find that some information in this list is incomplete, please don't hesitate +to let us know. + +<informaltable> +<tgroup cols="4"> +<thead> +<row> +<entry>Linux Driver / Soundcard</entry> +<entry>Fails under</entry> +<entry>Works under</entry> +<entry>Remarks</entry> +</row> +</thead> + +<tbody> +<row> +<entry>i810 driver (Intel 810 + AC97 Audio)</entry> +<entry>2.4.9</entry> +<entry>2.4.18, 2.2.20, commercial oss driver, alsa-0.5.12a with OSS emulation</entry> +<entry>driver causes cpu overload (see below)</entry> +</row> + +<row> +<entry>maestro 3/4 chipset</entry> +<entry>2.4.9</entry> +<entry>?</entry> +<entry>driver sometimes causes cpu overload (see below)</entry> +</row> + +<row> +<entry>aureal8820, aureal8830 drivers from sourceforge</entry> +<entry>2.4.17</entry> +<entry>?</entry> +<entry>driver triggers assertion / causes cpu overload (see below)</entry> +</row> + +<row> +<entry>OSS Commercial 3.9.4g with Aureal Vortex</entry> +<entry>?</entry> +<entry>?</entry> +<entry>system lockup</entry> +</row> + +<row> +<entry>ymfpci</entry> +<entry>2.4.0, 2.4.12</entry> +<entry>2.4.17</entry> +<entry>driver triggers assertion (see below)</entry> +</row> + + + +</tbody> +</tgroup> +</informaltable> +</para> +</answer> +</qandaentry> + + + +<qandaentry> +<question> +<para> +Why are there hardware specific problems and how do I see them? +</para> +</question> +<answer> +<para> +The usual problem is that the driver doesn't supply aRts with enough or accurate +enough information on when to write sound data. Most OSS drivers do supply +correct information, but not all. +</para> +<para> +You might notice that some other applications (like xmms) may not need this +data, and thus work correctly even with your hardware. However, &arts; needs +this data, so artsd might fail. This is still a bug in the driver, and not +in &arts;. +</para> +<para> +There are two kinds of behavior that artsd exposes on being run on an incorrect +driver. Either, it continously tries to feed new data, but never really +succeeds, which eventually leads to consuming all CPU power and reporting +<emphasis>cpu overload</emphasis> and exiting. The other problem is that artsd +might get supplied with wrong information how much to write. Artsd will then +<emphasis>stop with an assertion</emphasis> like: +<screen> +artsd: audiosubsys.cc:458: void Arts::AudioSubSystem::handleIO(int): +Assertion `len == can_write' failed. +Aborted +</screen> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +What is wrong in the driver if I get the cpu overload problem? +</para> +</question> +<answer> +<para> +Usually, artsd uses select() to find out when to write new data. Then, it +uses an ioctl(...GETOSPACE...) to find out how much data to write. Finally, +it writes this data. +</para> +<para> +A problem occurs if artsd is woken up either always or if there are minimal +amounts of data to write. The OSS documentation specifies that select() only +wakes up a process if there is at least one fragment to write. However, if +artsd is woken up if there isn't data to write, or very little, for instance +one sample, then it will keep writing little pieces of audio data, which can +be very costly, and eventually overload the cpu. +</para> +<para> +To fix this, the driver should wake up artsd only if there is a full fragment +to write. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +What is wrong in the driver if I get the assertion? +</para> +</question> +<answer> +<para> +Usually, artsd uses select() to find out when to write new data. Then, it +uses an ioctl(...GETOSPACE...) to find out how much data to write. Finally, +it writes this data. +</para> +<para> +If artsd can't write as much data as indicated by the ioctl, it will fail in +the assertion. To fix this, the driver should supply the correct amount of +free space. +</para> +</answer> +</qandaentry> +</qandaset> + +<qandaset id="faq-other"> +<title>Other Issues</title> + +<qandaentry> +<question> +<para> +I can't use &arts-builder;. It crashes when executing a module! +</para> +</question> +<answer> +<para> +The most likely cause is that you are using old structures or modules +which aren't supported with the &kde; 2 version. Unfortunately the +documentation which is on the web refers to &arts;-0.3.4.1 which is +quite outdated. The most often reported crash is: that performing an +execute structure in &arts-builder; results in the error message +<errorname>[artsd] Synth_PLAY: audio subsystem is already +used.</errorname> +</para> + +<para> +You should use a Synth_AMAN_PLAY instead of a Synth_PLAY module and the +problem will go away. Also see the &arts-builder; help file (hit +<keycap>F1</keycap> in &arts-builder;). +</para> + +<para> +Recent versions of &arts-builder; (&kde; 2.1 beta 1 and later) come with +a set of examples which you can use. +</para> +</answer> +</qandaentry> + +</qandaset> + +</chapter> diff --git a/doc/artsbuilder/future.docbook b/doc/artsbuilder/future.docbook new file mode 100644 index 00000000..529cc103 --- /dev/null +++ b/doc/artsbuilder/future.docbook @@ -0,0 +1,414 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant +V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="future-work"> +<title>Future Work</title> + +<para> +This section describes some of the &arts; work that is in progress. +Development progresses quickly, so this information may be out of date. +You should check the TODO list file and the <link +linkend="mailing-lists">mailing list</link> archives to see what new +functionality is planned. Feel free to get involved in new design and +implementation. +</para> + +<para> +This is a draft document which tries to give you an overview how new +technologies will be integrated in &arts;. Namely, it does cover the +following: +</para> + +<itemizedlist> +<listitem><para>How interfaces work.</para></listitem> +<listitem><para>Codecs - decoding of mp3 or wav streams in a form that +they can be used as data.</para></listitem> +<listitem><para>Video.</para></listitem> +<listitem><para>Threading.</para></listitem> +<listitem><para>Synchronization.</para></listitem> +<listitem><para>Dynamic expansion/masquerading.</para></listitem> +<listitem><para>Dynamic composition.</para></listitem> +<listitem><para>&GUI;</para></listitem> +<listitem><para>&MIDI;</para></listitem> +</itemizedlist> + +<para> +This is work in progress. However, it should be the base if you want to +see new technology in &arts;. It should give you a general idea how +these problems will be addressed. However, feel free to correct anything +you see here. +</para> + +<para> +Things that will be use &arts; technology (so please, coordinate your +efforts): +</para> + +<itemizedlist> +<listitem> +<para> +<application>KPhone</application> (voice over <acronym>IP</acronym>) +</para> +</listitem> + +<listitem> +<para> +&noatun; (video / audio player) +</para> +</listitem> + +<listitem> +<para> +&artscontrol; (sound server control program, for scopes) +</para> +</listitem> + +<listitem> +<para> +<application>Brahms</application> (music sequencer) +</para> +</listitem> + +<listitem> +<para><application>Kaiman</application> (&kde;2 media player - kmedia2 compliant) +</para> +</listitem> + +<listitem> +<para> +<application>mpglib</application>/<application>kmpg</application> +(<acronym>mpg</acronym> audio and video playing technology) +</para> +</listitem> + +<listitem> +<para> +<application>SDL</application> (direct media layer for games not +yet started but maybe nice) +</para> +</listitem> + +<listitem> +<para> +<application>electric ears</application> (author contacted me - status +unknown) +</para> +</listitem> +</itemizedlist> + +<sect1 id="interfaces-how"> +<title>How Interfaces Work</title> + +<!-- I think this is now obsolete and documented elsewhere ? --> + +<para> +&MCOP; interfaces are the base of the &arts; concept. They are the +network transparent equivalent to C++ classes. Whenever possible you +should orient your design towards interfaces. Interfaces consist of four +parts: +</para> + +<itemizedlist> +<listitem><para>Synchronous streams</para></listitem> +<listitem><para>Asynchronous streams</para></listitem> +<listitem><para>Methods</para></listitem> +<listitem><para>Attributes</para></listitem> +</itemizedlist> + +<para> +These can be mixed in any way you like. New technologies should be +defined in terms of interfaces. Read the sections about asynchronous +streams and synchronous streams, as well as the KMedia2 interfaces, +which are a good example how such things work +</para> + +<para> +Interfaces are specified in <literal role="extension">.idl</literal> +code and run through the <command>mcopidl</command> compiler. You +derive the +<classname><replaceable>Interfacename</replaceable>_impl</classname> +class to implement them, and use +<function>REGISTER_IMPLEMENTATION(Interfacename_impl)</function> to +insert your object implementations into the &MCOP; object system. +</para> + +</sect1> + +<sect1 id="codecs"> +<title>Codecs - Data Decoding</title> + +<para> +The kmedia2 interfaces allow you to ignore that wav files, mp3s and +whatever consist of data streams. Instead, you only implement methods to +play them. +</para> + +<para> +Thus, you can write a wave loading routine in a way that you can play +wave files (as PlayObject), but nobody else can use your code. +</para> + +<para> +Asynchronous streams would be the alternative. You define an interface +which allows you to pass data blocks in, and get data blocks out. This +looks like that in &MCOP;: +</para> + +<programlisting> +interface Codec { + in async byte stream indata; + out async byte stream outdata; +}; +</programlisting> + + +<para> +Of course codecs could also provide attributes to emit additional data, +such as format information. +</para> + +<programlisting> +interface ByteAudioCodec { + in async byte stream indata; + out async byte stream outdata; + readonly attribute samplingRate, bits, channels; +}; +</programlisting> + +<para> +This <interfacename>ByteAudioCodec</interfacename> for instance could be +connected to a <interfacename>ByteStreamToAudio</interfacename> object, +to make real float audio. +</para> + +<para> +Of course, other Codec types could involve directly emitting video data, +such as +</para> + +<programlisting> +interface VideoCodec { + in async byte stream indata; + out video stream outdata; /* note: video streams do not exist yet */ +}; +</programlisting> + +<para> +Most likely, a codec concept should be employed rather than the +<quote>you know how to play and I don't</quote> way for instance +<interfacename>WavPlayObject</interfacename> currently uses. However, +somebody needs to sit down and do some experiments before an +<acronym>API</acronym> can be finalized. +</para> + +</sect1> + +<sect1 id="video"> +<title>Video</title> + +<para> +My idea is to provide video as asynchronous streams of some native +&MCOP; data type which contains images. This data type is to be created +yet. Doing so, plugins which deal with video images could be connected +the same way audio plugins can be connected. +</para> + +<para> +There are a few things that are important not to leave out, namely: +</para> + +<itemizedlist> +<listitem> +<para> +There are <acronym>RGB</acronym> and <acronym>YUV</acronym> colorspaces. +</para> +</listitem> +<listitem> +<para> +The format should be somehow tagged to the stream. +</para> +</listitem> +<listitem> +<para> +Synchronization is important. +</para> +</listitem> +</itemizedlist> + +<para> +My idea is to leave it possible to reimplement the +<classname>VideoFrame</classname> class so that it can store stuff in a +shared memory segment. Doing so, even video streaming between different +processes would be possible without too much pain. +</para> + +<para> +However, the standard situation for video is that things are in the same +process, from the decoding to the rendering. +</para> + +<para> +I have done a prototypic video streaming implementation, which you can +download <ulink +url="http://space.twc.de/~stefan/kde/download/video-quickdraw.tar.gz">here +</ulink>. This would need to be integrated into &MCOP; after some +experiments. +</para> + +<para> +A rendering component should be provided that supports XMITSHM (with +<acronym>RGB</acronym> and <acronym>YUV</acronym>), Martin Vogt told me +he is working on such a thing. +</para> + +</sect1> + +<sect1 id="threading"> +<title>Threading</title> + +<para> +Currently, &MCOP; is all single threaded. Maybe for video we will no +longer be able to get around threading. Ok. There are a few things that +should be treated carefully: +</para> + + +<itemizedlist> +<listitem><para> +SmartWrappers - they are not threadsafe due to non-safe reference +counting and similar. +</para> +</listitem> +<listitem> +<para> +Dispatcher / I/O - also not threadsafe. +</para> +</listitem> +</itemizedlist> + +<para> +However, what I could imagine is to make selected modules threadsafe, +for both, synchronous and asynchronous streaming. That way - with a +thread aware flow system, you could schedule the signal flow over two or +more processors. This would also help audio a lot on multiprocessor +things. +</para> + +<para> +How it would work: +</para> + + +<itemizedlist> +<listitem> +<para>The Flow System decides which modules should calculate what - that +is: +</para> + <itemizedlist> + <listitem><para>video frames (with process_indata method)</para></listitem> + <listitem><para>synchronous audio streams + (calculateBlock)</para></listitem> + <listitem><para>other asynchronous streams, mainly byte + streams</para></listitem> + </itemizedlist> +</listitem> +<listitem> +<para> +Modules can calculate these things in own threads. For audio, it makes +sense to reuse threads (⪚ render on four threads for four processors, +no matter if 100 modules are running). For video and byte decompression, +it may be more confortable to have a blocking implementation in an own +thread, which is synchronized against the rest of &MCOP; by the flow +system. +</para> +</listitem> + +<listitem> +<para> +Modules may not use &MCOP; functionality (such as remote invocations) +during threaded operation. +</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="synchronization"> +<title>Synchronization</title> + +<para> +Video and &MIDI; (and audio) may require synchronization. Basically, that +is timestamping. The idea I have is to attach timestamps to asynchronous +streams, by adding one timestamp to each packet. If you send two video +frames, simply make it two packets (they are large anyway), so that you +can have two different time stamps. +</para> + +<para> +Audio should implicitely have time stamps, as it is synchronous. +</para> + +</sect1> + +<sect1 id="dynamic-composition"> +<title>Dynamic Composition</title> + +<para> +It should be possible to say: An effect FX is composed out of these +simpler modules. FX should look like a normal &MCOP; module (see +masquerading), but in fact consist of other modules. +</para> + +<para> +This is required for &arts-builder;. +</para> + +</sect1> + +<sect1 id="gui"> +<title>&GUI;</title> + +<para> +All &GUI; components will be &MCOP; modules. They should have attributes +like size, label, color, ... . A <acronym>RAD</acronym> builder +(&arts-builder;) should be able to compose them visually. +</para> + +<para> +The &GUI; should be saveable by saving the attributes. +</para> + +</sect1> + +<sect1 id="midi-stuff"> +<title>&MIDI;</title> + +<para> +The &MIDI; stuff will be implemented as asynchronous streams. There are +two options, one is using normal &MCOP; structures to define the types +and the other is to introduce yet another custom types. +</para> + +<para> +I think normal structures may be enough, that is something like: +</para> + +<programlisting> +struct MidiEvent { + byte b1,b2,b3; + sequence<byte> sysex; +} +</programlisting> + +<para> +Asynchronous streams should support custom stream types. +</para> + +</sect1> + +</chapter> + + diff --git a/doc/artsbuilder/glossary.docbook b/doc/artsbuilder/glossary.docbook new file mode 100644 index 00000000..12fd2dac --- /dev/null +++ b/doc/artsbuilder/glossary.docbook @@ -0,0 +1,164 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE glossary PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<glossary id="glossary"> + +<glossentry id="gloss-alsa"> +<glossterm><acronym>ALSA</acronym></glossterm> +<glossdef> +<para> +Advanced &Linux; Sound Architecture; a &Linux; sound card driver; not +currently included with the standard kernel source code. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-arts"> +<glossterm>&arts;</glossterm> +<glossdef> +<para> +Analog Real-Time Synthesizer; the name of the multimedia +architecture/library/toolkit used by the &kde; project (note +capitalization) +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-bsd"> +<glossterm><acronym>BSD</acronym></glossterm> +<glossdef> +<para> +Berkeley Software Distribution; here refers to any of several free +&UNIX;-compatible operating systems derived from <acronym>BSD</acronym> +&UNIX;. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-corba"> +<glossterm><acronym>CORBA</acronym></glossterm> +<glossdef> +<para> +Common Object Request Broker Architecture; a standard for implementing +object-oriented remote execution. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-cvs"> +<glossterm><acronym>CVS</acronym></glossterm> +<glossdef> +<para> +Concurrent Versions System; a software configuration management system +used by many software projects including &kde; and &arts;. +</para> +</glossdef> +</glossentry> + +<glossentry id="glos-fft"> +<glossterm><acronym>FFT</acronym></glossterm> +<glossdef> +<para> +Fast Fourier Transform; an algorithm for converting data from the time +to frequency domain; often used in signal processing. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-full-duplex"> +<glossterm>Full Duplex</glossterm> +<glossdef> +<para> +The ability of a sound card to simultaneously record and play audio. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-gpl"> +<glossterm><acronym>GPL</acronym></glossterm> +<glossdef> +<para> +<acronym>GNU</acronym> General Public License; a software license +created by the Free Software Foundation defining the terms for releasing +free software. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-gui"> +<glossterm>&GUI;</glossterm> +<glossdef> +<para> +Graphical User Interface +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-idl"> +<glossterm><acronym>IDL</acronym></glossterm> +<glossdef> +<para> +Interface Definition Language; a programming language independent format +for specifying interfaces (methods and data). +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-kde"> +<glossterm>&kde;</glossterm> +<glossdef> +<para> +K Desktop Environment; a project to develop a free graphical desktop +environment for &UNIX; compatible systems. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-lgpl"> +<glossterm><acronym>LGPL</acronym></glossterm> +<glossdef> +<para> +<acronym>GNU</acronym> Lesser General Public License; a software license +created by the Free Software Foundation defining the terms for releasing +free software; less restrictive than the <acronym>GPL</acronym> and +often used for software libraries. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-mcop"> +<glossterm>&MCOP;</glossterm> +<glossdef> +<para> +Multimedia COmmunication Protocol; the protocol used for communication +between &arts; software modules; similar to <acronym>CORBA</acronym> but +simpler and optimized for multimedia. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-midi"> +<glossterm>&MIDI;</glossterm> +<glossdef> +<para> +Musical Instrument Digital Interface; a standard protocol for +communication between electronic musical instruments; often also used to +refer to a file format for storing &MIDI; commands. +</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-oss"> +<glossterm><acronym>OSS</acronym></glossterm> +<glossdef> +<para> +Open Sound System; the sound drivers included with the &Linux; kernel +(sometimes called <acronym>OSS</acronym>/Free) or a commercial version +sold by 4Front Technologies. +</para> +</glossdef> +</glossentry> + +</glossary> diff --git a/doc/artsbuilder/gui.docbook b/doc/artsbuilder/gui.docbook new file mode 100644 index 00000000..d420bf8a --- /dev/null +++ b/doc/artsbuilder/gui.docbook @@ -0,0 +1,28 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<!-- +<chapter id="gui-elements"> +<title>&GUI; Elements</title> + +<sect1 id="gui-introduction"> +<title>Introduction</title> +<para> +</para> +</sect1> + +<sect1 id="parents"> +<title>Parents</title> +<para> +</para> +</sect1> + +<sect1 id="mixers"> +<title>Mixers</title> +<para> +</para> +</sect1> +</chapter> +--> diff --git a/doc/artsbuilder/helping.docbook b/doc/artsbuilder/helping.docbook new file mode 100644 index 00000000..72b2ff2b --- /dev/null +++ b/doc/artsbuilder/helping.docbook @@ -0,0 +1,246 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="contributing"> +<title>Contributing to &arts;</title> + +<sect1 id="how-to-help"> +<title>How You Can Help</title> + +<para> +The &arts; project can use help from developers to make existing +multimedia applications &arts;-aware, write new multimedia applications, +and enhance the capabilities of &arts;. However, you don't have to be a +developer to contribute. We can also use help from testers to submit bug +reports, translators to translate the application text and documentation +into other languages, artists to design bitmaps (especially for +<application>artsbuilder</application> modules), musicians to create +sample &arts; modules, and writers to write or proofread documentation. +</para> +</sect1> + +<sect1 id="mailing-lists"> +<title>Mailing Lists</title> + +<para> +Most development discussions on &arts; take place on two mailing +lists. This is the place to discuss new feature and implementation ideas +or ask for help with problems. +</para> + +<para> +The &kde; Multimedia mailing list is for general &kde; multimedia issues +including &arts; as well as the multimedia applications like &noatun; +and &aktion;. You can subscribe from the web page at +<ulink url="http://www.kde.org/mailinglists.html"> +http://www.kde.org/mailinglists.html</ulink> or send an email with the +subject set to <userinput>subscribe +<replaceable>your-email-address</replaceable></userinput> to +<email>kde-multimedia-request@kde.org</email>. The list is also archived +at <ulink url="http://lists.kde.org"> http://lists.kde.org</ulink>. +</para> + +<para> +The &arts; mailing list is for issues specific to &arts;, including +non-&kde; use of &arts;. To subscribe, send an email containing the +message body <userinput>subscribe +<replaceable>your-email-address</replaceable></userinput> to +<email>arts-request@space.twc.de</email>. The list is archived at +<ulink url="http://space.twc.de/~stefan/arts-archive"> +http://space.twc.de/~stefan/arts-archive</ulink>. +</para> + +</sect1> + +<sect1 id="coding-standards"> +<title>Coding Standards</title> + +<para> +For getting a consistent reading through all the sources, it is +important to keep the coding style the same, all over the &arts; +source. Please, even if you just write a module, try to write/format +your source accordingly, as it will make it easier for different people +to maintain the source tree, and easier to copy pieces of from one +source to another. +</para> + +<variablelist> +<varlistentry> +<term>Naming of member functions</term> +<listitem> +<para> +&Qt;/&Java; style. That means capitalization on word breaks, and first +letter always without capitalization; no underscores. +</para> +<para>This means for instance:</para> + +<programlisting> createStructureDesc() + updateWidget(); + start(); </programlisting> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Class members</term> +<listitem> +<para> +Class members are not capitalized, such as menubar or button. +</para> + +<para> +When there are accessing functions, the standard should be the &MCOP; +way, that is, when having an long member <function>foo</function>, which +shouldn't be visible directly, you create: +</para> + +<programlisting> foo(long new_value); + long foo(); </programlisting> + +<para> +functions to get and set the value. In that case, the real value of +<function>foo</function> should be stored in +<returnvalue>_foo</returnvalue>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Class names</term> +<listitem> +<para> +All classes should be wordwise capitalized, that means +<classname>ModuleView</classname>, +<classname>SynthModule</classname>. All classes that belong to the +libraries should use the &arts; namespace, like +<classname>Arts::Soundserver</classname>. +</para> +<para> +The implementations of &MCOP; classes should get called +<classname>Class_impl</classname>, such as +<classname>SoundServer_impl</classname>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Parameters</term> +<listitem> +<para> +Parameters are always uncapitalized. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Local variables</term> +<listitem> +<para> +Local variables are always uncapitalized, and may have names like +<varname>i</varname>, <varname>p</varname>, <varname>x</varname>, &etc; +where appropriate. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Tab width (Shift width)</term> +<listitem> +<para> +One tab is as long as 4 spaces. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Spaces in expressions</term> +<listitem> +<para> +You normally don't need to use spaces in expressions. You can however use +them between operator and their operands. However, if you put a space before +an operator (i.e. +), you also need to put a space after the operator. The only +exception to this are list-like expressions (with ,), where you should only put +a space after the ",", but not before. It's okay to omit the space here, too. +</para> +<para> +The following examples demonstrate good use of spaces: +</para> +<programlisting> +{ + int a,b; + int c, d, e; + int f = 4; + + a=b=c=d+e+f; + a = b = c = d + e + f; + + if(a == 4) { + a = b = c = (d+e)/2; + } + + while(b<3) + c--; + + arts_debug("%d\n", c); +} +</programlisting> +<para> +The following examples demonstrate how <emphasis>not</emphasis> to use spaces. +For function calls, after if, while, for, switch and so on, no space is being +written. +</para> +<programlisting> +{ + // BAD: if you write a list, write spaces only after the "," + int a , b , c , d , e , f; + + // BAD: non-symmetric use of spaces for = operator + a= 5; + + // BAD: if is considered a function, and isn't followed by a space + if (a == 5) { + } + + // BAD: don't write a space after while + while (a--) + b++; + + // BAD: functions names are not followed by a space + arts_debug ("%d\n", c); + + // BAD: neither are member names + Arts::Object o = Arts::Object::null (); +} +</programlisting> +</listitem> +</varlistentry> + + +<varlistentry> +<term>Naming of source files</term> +<listitem> +<para> +Source files should have no capitalization in the name. They should have +the name of the class when they implement a single class. Their +extension is <literal role="extension">.cc</literal> if they refer to +&Qt;/&GUI; independent code, and <literal +role="extension">.cpp</literal> if they refer to &Qt;/&GUI; dependant +code. Implementation files for interfaces should be called +<filename><replaceable>foo</replaceable>_impl</filename>, if Foo was the +name of the interface. +</para> + +<para> +&IDL; files should be called in a descriptive way for the collection of +interfaces they contain, also all lower case. Especially it is not good +to call an &IDL; file like the class itself, as the .mcopclass trader +and type info entries will collide, then. +</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +</chapter> diff --git a/doc/artsbuilder/images/Doc_MODUL.png b/doc/artsbuilder/images/Doc_MODUL.png Binary files differnew file mode 100644 index 00000000..fe131e74 --- /dev/null +++ b/doc/artsbuilder/images/Doc_MODUL.png diff --git a/doc/artsbuilder/images/Gui_AUDIO_MANAGER.png b/doc/artsbuilder/images/Gui_AUDIO_MANAGER.png Binary files differnew file mode 100644 index 00000000..5cc92920 --- /dev/null +++ b/doc/artsbuilder/images/Gui_AUDIO_MANAGER.png diff --git a/doc/artsbuilder/images/Gui_INSTRUMENT_MAPPER.png b/doc/artsbuilder/images/Gui_INSTRUMENT_MAPPER.png Binary files differnew file mode 100644 index 00000000..19231daa --- /dev/null +++ b/doc/artsbuilder/images/Gui_INSTRUMENT_MAPPER.png diff --git a/doc/artsbuilder/images/Gui_LABEL.png b/doc/artsbuilder/images/Gui_LABEL.png Binary files differnew file mode 100644 index 00000000..9ba2ce80 --- /dev/null +++ b/doc/artsbuilder/images/Gui_LABEL.png diff --git a/doc/artsbuilder/images/Gui_MIXER.png b/doc/artsbuilder/images/Gui_MIXER.png Binary files differnew file mode 100644 index 00000000..f6a036a7 --- /dev/null +++ b/doc/artsbuilder/images/Gui_MIXER.png diff --git a/doc/artsbuilder/images/Gui_PANEL.png b/doc/artsbuilder/images/Gui_PANEL.png Binary files differnew file mode 100644 index 00000000..c6ce0888 --- /dev/null +++ b/doc/artsbuilder/images/Gui_PANEL.png diff --git a/doc/artsbuilder/images/Gui_POTI.png b/doc/artsbuilder/images/Gui_POTI.png Binary files differnew file mode 100644 index 00000000..b40bf431 --- /dev/null +++ b/doc/artsbuilder/images/Gui_POTI.png diff --git a/doc/artsbuilder/images/Gui_SLIDER.png b/doc/artsbuilder/images/Gui_SLIDER.png Binary files differnew file mode 100644 index 00000000..7e9c83e7 --- /dev/null +++ b/doc/artsbuilder/images/Gui_SLIDER.png diff --git a/doc/artsbuilder/images/Gui_SUBPANEL.png b/doc/artsbuilder/images/Gui_SUBPANEL.png Binary files differnew file mode 100644 index 00000000..34bc5a77 --- /dev/null +++ b/doc/artsbuilder/images/Gui_SUBPANEL.png diff --git a/doc/artsbuilder/images/Gui_WINDOW.png b/doc/artsbuilder/images/Gui_WINDOW.png Binary files differnew file mode 100644 index 00000000..677ada48 --- /dev/null +++ b/doc/artsbuilder/images/Gui_WINDOW.png diff --git a/doc/artsbuilder/images/Interface_MIDI_NOTE.png b/doc/artsbuilder/images/Interface_MIDI_NOTE.png Binary files differnew file mode 100644 index 00000000..bc2d5ad0 --- /dev/null +++ b/doc/artsbuilder/images/Interface_MIDI_NOTE.png diff --git a/doc/artsbuilder/images/Makefile.am b/doc/artsbuilder/images/Makefile.am new file mode 100644 index 00000000..1b7d1e0f --- /dev/null +++ b/doc/artsbuilder/images/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = artsbuilder/images + diff --git a/doc/artsbuilder/images/Synth_ADD.png b/doc/artsbuilder/images/Synth_ADD.png Binary files differnew file mode 100644 index 00000000..e06e47a0 --- /dev/null +++ b/doc/artsbuilder/images/Synth_ADD.png diff --git a/doc/artsbuilder/images/Synth_ATAN_SATURATE.png b/doc/artsbuilder/images/Synth_ATAN_SATURATE.png Binary files differnew file mode 100644 index 00000000..c8bea2a0 --- /dev/null +++ b/doc/artsbuilder/images/Synth_ATAN_SATURATE.png diff --git a/doc/artsbuilder/images/Synth_BUS_DOWNLINK.png b/doc/artsbuilder/images/Synth_BUS_DOWNLINK.png Binary files differnew file mode 100644 index 00000000..a2ad7c93 --- /dev/null +++ b/doc/artsbuilder/images/Synth_BUS_DOWNLINK.png diff --git a/doc/artsbuilder/images/Synth_BUS_UPLINK.png b/doc/artsbuilder/images/Synth_BUS_UPLINK.png Binary files differnew file mode 100644 index 00000000..3253ce69 --- /dev/null +++ b/doc/artsbuilder/images/Synth_BUS_UPLINK.png diff --git a/doc/artsbuilder/images/Synth_CDELAY.png b/doc/artsbuilder/images/Synth_CDELAY.png Binary files differnew file mode 100644 index 00000000..e9df7981 --- /dev/null +++ b/doc/artsbuilder/images/Synth_CDELAY.png diff --git a/doc/artsbuilder/images/Synth_COMPRESSOR.png b/doc/artsbuilder/images/Synth_COMPRESSOR.png Binary files differnew file mode 100644 index 00000000..2452a237 --- /dev/null +++ b/doc/artsbuilder/images/Synth_COMPRESSOR.png diff --git a/doc/artsbuilder/images/Synth_DEBUG.png b/doc/artsbuilder/images/Synth_DEBUG.png Binary files differnew file mode 100644 index 00000000..9c03a732 --- /dev/null +++ b/doc/artsbuilder/images/Synth_DEBUG.png diff --git a/doc/artsbuilder/images/Synth_DELAY.png b/doc/artsbuilder/images/Synth_DELAY.png Binary files differnew file mode 100644 index 00000000..dba8d715 --- /dev/null +++ b/doc/artsbuilder/images/Synth_DELAY.png diff --git a/doc/artsbuilder/images/Synth_DIV.png b/doc/artsbuilder/images/Synth_DIV.png Binary files differnew file mode 100644 index 00000000..5b811cdd --- /dev/null +++ b/doc/artsbuilder/images/Synth_DIV.png diff --git a/doc/artsbuilder/images/Synth_ENVELOPE_ADSR.png b/doc/artsbuilder/images/Synth_ENVELOPE_ADSR.png Binary files differnew file mode 100644 index 00000000..31bda8ca --- /dev/null +++ b/doc/artsbuilder/images/Synth_ENVELOPE_ADSR.png diff --git a/doc/artsbuilder/images/Synth_FILEPLAY.png b/doc/artsbuilder/images/Synth_FILEPLAY.png Binary files differnew file mode 100644 index 00000000..c68dec67 --- /dev/null +++ b/doc/artsbuilder/images/Synth_FILEPLAY.png diff --git a/doc/artsbuilder/images/Synth_FM_SOURCE.png b/doc/artsbuilder/images/Synth_FM_SOURCE.png Binary files differnew file mode 100644 index 00000000..a0da9390 --- /dev/null +++ b/doc/artsbuilder/images/Synth_FM_SOURCE.png diff --git a/doc/artsbuilder/images/Synth_FREQUENCY.png b/doc/artsbuilder/images/Synth_FREQUENCY.png Binary files differnew file mode 100644 index 00000000..4e038f69 --- /dev/null +++ b/doc/artsbuilder/images/Synth_FREQUENCY.png diff --git a/doc/artsbuilder/images/Synth_MIDI_DEBUG.png b/doc/artsbuilder/images/Synth_MIDI_DEBUG.png Binary files differnew file mode 100644 index 00000000..30c18efa --- /dev/null +++ b/doc/artsbuilder/images/Synth_MIDI_DEBUG.png diff --git a/doc/artsbuilder/images/Synth_MIDI_ROUTER.png b/doc/artsbuilder/images/Synth_MIDI_ROUTER.png Binary files differnew file mode 100644 index 00000000..6115b6b4 --- /dev/null +++ b/doc/artsbuilder/images/Synth_MIDI_ROUTER.png diff --git a/doc/artsbuilder/images/Synth_MUL.png b/doc/artsbuilder/images/Synth_MUL.png Binary files differnew file mode 100644 index 00000000..0c98e4c8 --- /dev/null +++ b/doc/artsbuilder/images/Synth_MUL.png diff --git a/doc/artsbuilder/images/Synth_NIL.png b/doc/artsbuilder/images/Synth_NIL.png Binary files differnew file mode 100644 index 00000000..997ef1e0 --- /dev/null +++ b/doc/artsbuilder/images/Synth_NIL.png diff --git a/doc/artsbuilder/images/Synth_PLAY.png b/doc/artsbuilder/images/Synth_PLAY.png Binary files differnew file mode 100644 index 00000000..7f318b78 --- /dev/null +++ b/doc/artsbuilder/images/Synth_PLAY.png diff --git a/doc/artsbuilder/images/Synth_PLAY_AKAI.png b/doc/artsbuilder/images/Synth_PLAY_AKAI.png Binary files differnew file mode 100644 index 00000000..6e5c7988 --- /dev/null +++ b/doc/artsbuilder/images/Synth_PLAY_AKAI.png diff --git a/doc/artsbuilder/images/Synth_PLAY_AKAIS.png b/doc/artsbuilder/images/Synth_PLAY_AKAIS.png Binary files differnew file mode 100644 index 00000000..9b8a95cd --- /dev/null +++ b/doc/artsbuilder/images/Synth_PLAY_AKAIS.png diff --git a/doc/artsbuilder/images/Synth_PLAY_WAV.png b/doc/artsbuilder/images/Synth_PLAY_WAV.png Binary files differnew file mode 100644 index 00000000..61d714ea --- /dev/null +++ b/doc/artsbuilder/images/Synth_PLAY_WAV.png diff --git a/doc/artsbuilder/images/Synth_PSCALE.png b/doc/artsbuilder/images/Synth_PSCALE.png Binary files differnew file mode 100644 index 00000000..56e645b9 --- /dev/null +++ b/doc/artsbuilder/images/Synth_PSCALE.png diff --git a/doc/artsbuilder/images/Synth_RC.png b/doc/artsbuilder/images/Synth_RC.png Binary files differnew file mode 100644 index 00000000..b86b1dfb --- /dev/null +++ b/doc/artsbuilder/images/Synth_RC.png diff --git a/doc/artsbuilder/images/Synth_SEQUENCE.png b/doc/artsbuilder/images/Synth_SEQUENCE.png Binary files differnew file mode 100644 index 00000000..25594c28 --- /dev/null +++ b/doc/artsbuilder/images/Synth_SEQUENCE.png diff --git a/doc/artsbuilder/images/Synth_SEQUENCE_FREQ.png b/doc/artsbuilder/images/Synth_SEQUENCE_FREQ.png Binary files differnew file mode 100644 index 00000000..07126bf7 --- /dev/null +++ b/doc/artsbuilder/images/Synth_SEQUENCE_FREQ.png diff --git a/doc/artsbuilder/images/Synth_SHELVE_CUTOFF.png b/doc/artsbuilder/images/Synth_SHELVE_CUTOFF.png Binary files differnew file mode 100644 index 00000000..9a97e853 --- /dev/null +++ b/doc/artsbuilder/images/Synth_SHELVE_CUTOFF.png diff --git a/doc/artsbuilder/images/Synth_STD_EQUALIZER.png b/doc/artsbuilder/images/Synth_STD_EQUALIZER.png Binary files differnew file mode 100644 index 00000000..7a3955f2 --- /dev/null +++ b/doc/artsbuilder/images/Synth_STD_EQUALIZER.png diff --git a/doc/artsbuilder/images/Synth_STRUCT_KILL.png b/doc/artsbuilder/images/Synth_STRUCT_KILL.png Binary files differnew file mode 100644 index 00000000..6c4d7927 --- /dev/null +++ b/doc/artsbuilder/images/Synth_STRUCT_KILL.png diff --git a/doc/artsbuilder/images/Synth_WAVE_SIN.png b/doc/artsbuilder/images/Synth_WAVE_SIN.png Binary files differnew file mode 100644 index 00000000..6d26eab6 --- /dev/null +++ b/doc/artsbuilder/images/Synth_WAVE_SIN.png diff --git a/doc/artsbuilder/images/Synth_WAVE_SQUARE.png b/doc/artsbuilder/images/Synth_WAVE_SQUARE.png Binary files differnew file mode 100644 index 00000000..ba99e85c --- /dev/null +++ b/doc/artsbuilder/images/Synth_WAVE_SQUARE.png diff --git a/doc/artsbuilder/images/Synth_WAVE_TRI.png b/doc/artsbuilder/images/Synth_WAVE_TRI.png Binary files differnew file mode 100644 index 00000000..62083f40 --- /dev/null +++ b/doc/artsbuilder/images/Synth_WAVE_TRI.png diff --git a/doc/artsbuilder/images/Synth_XFADE.png b/doc/artsbuilder/images/Synth_XFADE.png Binary files differnew file mode 100644 index 00000000..90498689 --- /dev/null +++ b/doc/artsbuilder/images/Synth_XFADE.png diff --git a/doc/artsbuilder/images/schema1.png b/doc/artsbuilder/images/schema1.png Binary files differnew file mode 100644 index 00000000..8bd236d0 --- /dev/null +++ b/doc/artsbuilder/images/schema1.png diff --git a/doc/artsbuilder/images/schema2.png b/doc/artsbuilder/images/schema2.png Binary files differnew file mode 100644 index 00000000..2d70af0b --- /dev/null +++ b/doc/artsbuilder/images/schema2.png diff --git a/doc/artsbuilder/images/schema3.png b/doc/artsbuilder/images/schema3.png Binary files differnew file mode 100644 index 00000000..9e1adf41 --- /dev/null +++ b/doc/artsbuilder/images/schema3.png diff --git a/doc/artsbuilder/images/schema4.png b/doc/artsbuilder/images/schema4.png Binary files differnew file mode 100644 index 00000000..834ac2ed --- /dev/null +++ b/doc/artsbuilder/images/schema4.png diff --git a/doc/artsbuilder/index.docbook b/doc/artsbuilder/index.docbook new file mode 100644 index 00000000..ba6649a1 --- /dev/null +++ b/doc/artsbuilder/index.docbook @@ -0,0 +1,393 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&arts;" > + <!ENTITY tools SYSTEM "tools.docbook"> + <!ENTITY artsbuilder-doc SYSTEM "artsbuilder.docbook"> + <!ENTITY detail SYSTEM "detail.docbook"> + <!ENTITY arts-midi SYSTEM "midi.docbook"> + <!ENTITY gui SYSTEM "gui.docbook"> + <!ENTITY mcop-ref SYSTEM "mcop.docbook"> + <!ENTITY arts-mcop SYSTEM "mcop.docbook"> + <!ENTITY apis SYSTEM "apis.docbook"> + <!ENTITY modules SYSTEM "modules.docbook"> + <!ENTITY porting SYSTEM "porting.docbook"> + <!ENTITY helping SYSTEM "helping.docbook"> + <!ENTITY future SYSTEM "future.docbook"> + <!ENTITY references SYSTEM "references.docbook"> + <!ENTITY arts-faq SYSTEM "faq.docbook"> + <!ENTITY arts-glossary SYSTEM "glossary.docbook"> + <!ENTITY digitalaudio SYSTEM "digitalaudio.docbook"> + <!ENTITY midiintro SYSTEM "midiintro.docbook"> + <!ENTITY MCOP "<acronym>MCOP</acronym>"> + <!ENTITY DCOP "<acronym>DCOP</acronym>"> + <!ENTITY MIDI "<acronym>MIDI</acronym>"> + <!ENTITY mcopidl "<application>mcopidl</application>"> + <!ENTITY IDL "<acronym>IDL</acronym>"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &arts; Handbook</title> +<authorgroup> + +<author> +<firstname>Stefan</firstname> +<surname>Westerfeld</surname> +<affiliation> +<address><email>stefan@space.twc.de</email></address> +</affiliation> +</author> + +<author> +<firstname>Jeff</firstname> +<surname>Tranter</surname> +<affiliation> +<address><email>tranter@kde.org</email></address> +</affiliation> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>1999-2001</year> +<holder>Stefan Westerfeld & Jeff Tranter</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2001-06-10</date> +<releaseinfo>1.00.09</releaseinfo> + +<abstract><para>This handbook describes &arts;, the Analog Real-time +Synthesizer.</para> + +</abstract> + +<keywordset> +<keyword>aRts</keyword> +<keyword>artsbuilder</keyword> +<keyword>synthesizer</keyword> +<keyword>multimedia</keyword> +<keyword>structure</keyword> +<keyword>music</keyword> +<keyword>sound</keyword> +<keyword>KDE</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<sect1 id="what-is-arts"> +<title>What is &arts;?</title> + +<para>The Analog Real-Time Synthesizer, or &arts;, is a modular system +for synthesizing sound and music on a digital computer. Using small +building blocks called modules, the user can easily build complex audio +processing tools. Modules typically provide functions such as sound +waveform generators, filters, audio effects, mixing, and playback of +digital audio in different file formats.</para> + +<para>The &artsd; sound server mixes audio from several sources in real +time, allowing multiple sound applications to transparently share access +to sound hardware.</para> + +<para>Using &MCOP;, the Multimedia Communication Protocol, multimedia +applications can be network transparent, authenticated for security, and +cross-platform using interfaces defined in a language-independent way +using &IDL;. Support is also provided for non &arts;-aware legacy +applications. As a core component of the &kde; 2 desktop environment, +&arts; provides the basis for the &kde; multimedia architecture, and +will in future support more media types including video. Like &kde;, +&arts; runs on a number of operating systems, including &Linux; and BSD +variants. It can also be used independently of &kde;.</para> + +</sect1> + +<sect1 id="using-this-manual"> +<title>Using This Manual</title> + +<para>This manual is intended to provide comprehensive documentation on +&arts; for users at different skill levels. Depending on whether you are +a casual user of multimedia applications that make use of &arts; or a +multimedia application developer, you may want to take different paths +through the manual.</para> + +<para>It is suggested that you first read the <link +linkend="installation">Downloading and Building &arts;</link> chapter if +you need to get &arts; initially installed and running. If you already +have a working system, likely bundled with your operating system +distribution, you may choose to skip this section.</para> + +<para>You should then read the sections in the <link +linkend="arts-tools">&arts; Tools</link> chapter, especially &artsd;, +artscontrol;, &artsshell;, and &artsdsp;. This will help you make the +most effective use of &arts;.</para> + +<para>If you are interested in going further with &arts;, read the +chapter on <link linkend="artsbuilder">&arts-builder;</link> and go +through the tutorial. This should give you an appreciation of the +powerful capabilities of &arts; and the provided modules that can be +used without the need to be a programmer.</para> + +<para>If you want to know more about the internals of &arts;, either to +develop multimedia applications or extend &arts; itself, read some or +all of the chapter <link linkend="arts-in-detail">&arts; in +Detail</link>. This should give you an understanding of all of the +concepts that are prerequisites to &arts; software development.</para> + +<para>If you are interested specifically in the <acronym>MIDI</acronym> +capabilities of &arts;, you should read the chapter on <link +linkend="midi">&MIDI;</link>.</para> + +<!-- TODO +<para>To learn more about the &arts; graphical elements, either as an advanced +user of artsbuilder or to create new elements, read the section on <link +linkend="gui-elements"><acronym>GUI</acronym> Elements</link>.</para> +--> + +<para>If you want to develop &arts;-aware multimedia applications, the +<link linkend="arts-apis">&arts; Application Programming +Interfaces</link> chapter covers the different <acronym>API</acronym>s +in detail.</para> + +<para>If you want to extend &arts; by creating new modules, read the +<link linkend="arts-modules">&arts; Modules</link> chapter.</para> + +<para>If you are modifying an existing application to run under &arts;, +read the chapter on <link linkend="porting">Porting Applications to +&arts;</link>.</para> + +<para>You you can find out how to help contribute to the &arts; project +in the <link linkend="contributing">Contributing to &arts;</link> +chapter, read about upcoming &arts; development in the chapter on <link +linkend="future-work">Future Work</link>, and find links to more +information in the <link linkend="references">References</link> +section.</para> + +<para>We have also rounded out the manual with some additional material, +including <link linkend="faq">answers to frequently asked +questions</link>, a <link linkend="contributors">list of +contributors</link>, the details on &arts; <link +linkend="copyright-and-licenses">copyright and licensing</link>, and +some background material on <link linkend="intro-digital-audio">digital +audio</link> and <link +linkend="midi-introduction">&MIDI;</link>. A <link +linkend="glossary">glossary</link> of terms is also included.</para> + +<note> +<para> +This manual is still very much a work in progress. You are welcome to +contribute by writing portions of it, but if you wish to do so, contact +Jeff Tranter <email>tranter@kde.org</email> or Stefan Westerfeld +<email>stefan@space.twc.de</email> first to avoid duplication of effort. +</para> +</note> + +</sect1> + +<sect1 id="history"> +<title>History</title> + +<para> +In late 1997 Stefan Westerfeld started working on a real-time, modular +system for sound synthesis. The code initially ran on a PowerPC system +running &AIX;. This first implementation was quite simple but supported +a full-featured flow system that was able to do such things as play MP3 +files and pipe audio streams through effects modules. +</para> + + +<para>The next step was to implement a &GUI; so that modules could be +manipulated graphically. Stefan had had some good experience using +&kde;, so that was chosen as the &GUI; toolkit, (knowing that it might +be necessary to do a GNOME/Gtk+ version as well) and this later led to +using &Linux; as the main development platform. Originally named +<application>ksynth</application>, the project was renamed &arts; and +the pace of development accelerated. The project at this stage was quite +complete, with a <acronym>CORBA</acronym>-based protocol, dozens of +modules, a graphical module editing tool, C and C++ +<acronym>API</acronym>s, documentation, utilities, and a mailing list +and web site with a small group of developers. The project had come a +long way after only a little more than a year of development.</para> + +<para>As the &kde; team started planning for &kde; 2.0, it became clear +that &kde; needed a more powerful infrastructure for sound and other +streaming media. It was decided to adapt &arts;, as it was a good step +in this direction with a proven architecture. Much new development +effort went into this new version of &arts;, most notably the +replacement of the <acronym>CORBA</acronym> code with an entirely new +subsystem, &MCOP;, optimized for multimedia. Version 0.4 of &arts; was +included in the &kde; 2.0 release.</para> + +<para>Work continues on &arts;, improving performance and adding new +functionality. It should be noted that even though &arts; is now a core +component of &kde;, it can be used without &kde;, and is also being used +for applications that go beyond traditional multimedia. The project has +attracted some interest from the GNOME team, opening up the possibility +that it may someday become the standard multimedia architecture for +&UNIX; desktop systems.</para> + +</sect1> + +</chapter> + +&tools; +&artsbuilder-doc; +&detail; +&arts-midi; +&gui; +&mcop-ref; +&apis; +&modules; +&porting; +&helping; +&future; +&references; +&arts-faq; + +<chapter id="copyright-and-licenses"> + +<title>&arts; Copyright and Licensing</title> + +<para>&arts; software copyright 1998-2001 Stefan Westerfeld +<email>stefan@space.twc.de</email></para> + +<para><anchor id="contributors" /> +Documentation copyright 1999-2001 +Stefan Westerfeld <email>stefan@space.twc.de</email> and +Jeff Tranter <email>tranter@kde.org</email>. +</para> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; + +<para> +All libraries that are in &arts; are licensed under the terms of the +<acronym>GNU</acronym> Lesser General Public license. The vast majority of the +&arts; code is in the libraries, including the whole of <acronym>MCOP</acronym> +and ArtsFlow. This allows the libraries to be used for non-free/non-open source +applications if desired. +</para> + +<para>There are a few programs (such as <application>artsd</application>), that +are released under the terms of the <acronym>GNU</acronym> General Public +License. As there have been different opinions on whether or not linking +<acronym>GPL</acronym> programs with &Qt; is legal, I also added an explicit +notice which allows that, in addition to the <acronym>GPL</acronym>: permission +is also granted to link this program with the &Qt; library, treating &Qt; like a +library that normally accompanies the operating system kernel, whether or not +that is in fact the case.</para> + +</chapter> + +<appendix id="installation"> +<title>Installing &arts;</title> + +<para> +In order to use &arts; you obviously need to have it installed and running on +your system. There are two approaches for doing this, which are described in the +next sections. +</para> + +<sect1 id="binary-install"> +<title>Installing a Precompiled Binary Release</title> + +<para> +The quickest and easiest way to get &arts; up and running is to install +precompiled binary packages for your system. Most recent &Linux; distributions +include &kde;, and if it is &kde; 2.0 or later it will include &arts;. If &kde; +is not included on your installation media it may be available as a download +from your operating system vendor. Alternatively it may be available from third +parties. Make sure that you use packages that are compatible with your operating +system version. +</para> + +<para> +A basic install of &kde; will include the sound server, allowing most +applications to play sound. If you want the full set of multimedia tools and +applications you will likely need to install additional optional packages. +</para> + +<para> +The disadvantage of using precompiled binaries is that they may not be the most +recent version of &arts;. This is particularly likely if they are provided on +&CD-ROM;, as the pace of development of &arts; and &kde; is such that &CD-ROM; +media cannot usually keep pace. You may also find that, if you have one of the +less common architectures or operating system distributions, precompiled binary +packages may not be available and you will need to use the second method. +</para> + +</sect1> + +<sect1 id="source-install"> +<title>Building From Source</title> + +<para> +While time consuming, the most flexible way to build &arts; is to compile it +yourself from source code. This ensures you have a version compiled optimally +for your system configuration and allows you to build the most recent version. +</para> + +<para> +You have two choices here -- you can either install the most recent stable +version included with &kde; or you can get the most recent (but possibly +unstable) version directly from the &kde; project <acronym>CVS</acronym> +repository. Most users who aren't developing for &arts; should use the stable +version. You can download it from <ulink +url="ftp://ftp.kde.org">ftp://ftp.kde.org</ulink> or one of the many mirror +sites. If you are actively developing for &arts; you probably want to use the +<acronym>CVS</acronym> version. If you want to use aRts without KDE, you can +download a standalone development snapshot from +<ulink url="http://space.twc.de/~stefan/kde/arts-snapshot-doc.html"> +http://space.twc.de/~stefan/kde/arts-snapshot-doc.html</ulink>. +</para> + +<para> +Note that if you are building from <acronym>CVS</acronym>, some components +of &arts; (&ie; the basic core components including the sound server) are found +in the <acronym>CVS</acronym> module kdelibs, while additional components (⪚ +<application>artsbuilder</application>) are included in the. This may change in +the future. You may also find a version in the kmusic module; this is the old +(pre-&kde; 2.0) version which is now obsolete. +</para> + +<para> +The requirements for building &arts; are essentially the same as for building +&kde;. The configure scripts should detect your system configuration and +indicate if any required components are missing. Make sure that you have a +working sound driver on your system (either the <acronym>OSS</acronym>/Free +driver in the kernel, <acronym>OSS</acronym> driver from 4Front +Technologies, or +<acronym>ALSA</acronym> driver with <acronym>OSS</acronym> emulation). +</para> + +<para>More information on downloading and installing &kde; (including &arts;) +can be found in the <ulink +url="http://www.kde.org/documentation/faq/index.html">&kde; +&FAQ;</ulink>.</para> + +</sect1> + +</appendix> + +&digitalaudio; +&midiintro; +&arts-glossary; + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:nil +End: +--> diff --git a/doc/artsbuilder/mcop.docbook b/doc/artsbuilder/mcop.docbook new file mode 100644 index 00000000..86aa03b5 --- /dev/null +++ b/doc/artsbuilder/mcop.docbook @@ -0,0 +1,2274 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="mcop"> +<title>&MCOP;: Object Model and Streaming</title> + +<sect1 id="mcop-overview"> + +<title>Overview</title> + +<para> +&MCOP; is the standard &arts; uses for: +</para> + +<itemizedlist> +<listitem> +<para> +Communication between objects. +</para> +</listitem> + +<listitem> +<para> +Network transparency. +</para> +</listitem> + +<listitem> +<para> +Describing object interfaces. +</para> +</listitem> + +<listitem> +<para> +Language independancy. +</para> +</listitem> +</itemizedlist> + +<para> +One major aspect of &MCOP; is the <emphasis>interface description +language</emphasis>, &IDL;, in which many of the &arts; interfaces and +<acronym>API</acronym>s are defined in a language independent way. +</para> + +<para> +To use &IDL; interfaces from C++, is compiled by the &IDL; +compiler into C++ code. When you implement an interface, you derive from +the skeleton class the &IDL; compiler has generated. When you use an +interface, you do so using a wrapper. This way, &MCOP; can use a +protocol if the object you are talking to is not local - you get network +transparency. +</para> + +<para> +This chapter is supposed to describe the basic features of the object +model that results from the use of &MCOP;, the protocol, how do use +&MCOP; in C++ (language binding), and so on. +</para> + +</sect1> + +<sect1 id="interfaces"> + +<title>Interfaces and &IDL;</title> + +<para> +Many of the services provided by &arts;, such as modules and the sound +server, are defined in terms of <acronym>interfaces</acronym>. +Interfaces are specified in a programming language independent format: +&IDL;. +</para> + +<para> +This allows many of the implementation details such as the format of +multimedia data streams, network transparency, and programming language +dependencies, to be hidden from the specification for the interface. A +tool, &mcopidl;, translates the interface +definition into a specific programming language (currently only C++ is +supported). +</para> + +<para> +The tool generates a skeleton class with all of the boilerplate code and +base functionality. You derive from that class to implement the features +you want. +</para> + +<para> +The &IDL; used by &arts; is similar to that used by +<acronym>CORBA</acronym> and <acronym>DCOM</acronym>. +</para> + +<para> +&IDL; files can contain: +</para> + +<itemizedlist> +<listitem> +<para> +C-style #include directives for other &IDL; files. +</para> +</listitem> + +<listitem> +<para> +Definitions of enumerated and struct types, as in C/C++. +</para> +</listitem> + +<listitem> +<para> +Definitions of interfaces. +</para> +</listitem> +</itemizedlist> + +<para> +In &IDL;, interfaces are defined much like a C++ class or C struct, +albeit with some restrictions. Like C++, interfaces can subclass other +interfaces using inheritance. Interface definitions can include three +things: streams, attributes, and methods. +</para> + +<sect2 id="streams"> + +<title>Streams</title> + +<para> +Streams define multimedia data, one of the most important components of +a module. Streams are defined in the following format: +</para> + +<para> +[ async ] in|out [ multi ] <replaceable>type</replaceable> stream <replaceable>name</replaceable> [ , <replaceable>name</replaceable> ] ; +</para> + +<para> +Streams have a defined direction in reference to the module, as +indicated by the required qualifiers in or out. The type argument +defines the type of data, which can be any of the types described later +for attributes (not all are currently supported). Many modules use the +stream type audio, which is an alias for float since that is the +internal data format used for audio stream. Multiple streams of the same +type can defined in the same definition uisng comma separated names. +</para> + +<para> +Streams are by default synchronous, which means they are continuous +flows of data at a constant rate, such as <acronym>PCM</acronym> +audio. The async qualifier specifies an asynchronous stream, which is +used for non-continuous data flows. The most common example of an async +stream is &MIDI; messages. +</para> + +<para> +The multi keyword, only valid for input streams, indicates that the +interface supports a variable number of inputs. This is useful for +implementing devices such as mixers that can accept any number of input +streams. +</para> + +</sect2> +<sect2 id="attributes"> + +<title>Attributes</title> + +<para> +Attributes are data associated with an instance of an interface. They +are declared like member variables in C++, and can can use any of the +primitive types boolean, byte, long, string, or float. You can also use +user-defined struct or enum types as well as variable sized sequences +using the syntax sequence<type>. Attributes can optionally be +marked readonly. +</para> + +</sect2> +<sect2 id="methods"> + +<title>Methods</title> + +<para> +As in C++, methods can be defined in interfaces. The method parameters +are restricted to the same types as attributes. The keyword oneway +indicates a method which returns immediately and is executed +asynchronously. +</para> + +</sect2> + +<sect2 id="standardinterfaces"> + +<title>Standard Interfaces</title> + +<para> +Several standard module interfaces are already defined for you in +&arts;, such as <interfacename>StereoEffect</interfacename>, and +<interfacename>SimpleSoundServer</interfacename>. +</para> + +</sect2> + +<sect2 id="example"> +<title>Example</title> + +<para> +A simple example of a module taken from &arts; is the constant delay +module, found in the file +<filename>kdemultimedia/arts/modules/artsmodules.idl</filename>. The +interface definition is listed below. +</para> + +<programlisting> +interface Synth_CDELAY : SynthModule { + attribute float time; + in audio stream invalue; + out audio stream outvalue; +}; +</programlisting> + +<para> +This modules inherits from +<interfacename>SynthModule</interfacename>. That interface, defined in +<filename>artsflow.idl</filename>, defines the standard methods +implemented in all music synthesizer modules. +</para> + +<para> +The CDELAY effect delays a stereo audio stream by the time value +specified as a floating point parameter. The interface definition has an +attribute of type float to store the delay value. It defines two input +audio streams and two output audio streams (typical of stereo +effects). No methods are required other than those it inherits. +</para> + +</sect2> + +</sect1> + +<sect1 id="more-about-streams"> +<title>More About Streams</title> + +<para> +This section covers some additional topics related to streams. +</para> + +<sect2 id="stream-types"> +<title>Stream Types</title> + +<para> +There are various requirements for how a module can do streaming. To +illustrate this, consider these examples: +</para> + +<itemizedlist> +<listitem> +<para> +Scaling a signal by a factor of two. +</para> +</listitem> + +<listitem> +<para> +Performing sample frequency conversion. +</para> +</listitem> + +<listitem> +<para> +Decompressing a run-length encoded signal. +</para> +</listitem> + +<listitem> +<para> +Reading &MIDI; events from <filename +class="devicefile">/dev/midi00</filename> and inserting them into a +stream. +</para> +</listitem> +</itemizedlist> + +<para> +The first case is the simplest: upon receiving 200 samples of input the +module produces 200 samples of output. It only produces output when it +gets input. +</para> + +<para> +The second case produces different numbers of output samples when given +200 input samples. It depends what conversion is performed, but the +number is known in advance. +</para> + +<para> +The third case is even worse. From the outset you cannot even guess how +much data 200 input bytes will generate (probably a lot more than 200 +bytes, but...). +</para> + +<para> +The last case is a module which becomes active by itself, and sometimes +produces data. +</para> + +<para> +In &arts;s-0.3.4, only streams of the first type were handled, and most +things worked nicely. This is probably what you need most when writing +modules that process audio. The problem with the other, more complex +types of streaming, is that they are hard to program, and that you don't +need the features most of the time. That is why we do this with two +different stream types: synchronous and asynchronous. +</para> + +<para> +Synchronous streams have these characteristics: +</para> + +<itemizedlist> +<listitem> +<para> +Modules must be able to calculate data of any length, given enough +input. +</para> +</listitem> + +<listitem> +<para> +All streams have the same sampling rate. +</para> +</listitem> + +<listitem> +<para> +The <function>calculateBlock()</function> function will be called when +enough data is available, and the module can rely on the pointers +pointing to data. +</para> +</listitem> + +<listitem> +<para> +There is no allocation and deallocation to be done. +</para> +</listitem> +</itemizedlist> + +<para> +Asynchronous streams, on the other hand, have this behavior: +</para> + +<itemizedlist> +<listitem> +<para> +Modules may produce data sometimes, or with varying sampling rate, or +only if they have input from some filed descriptor. They are not bound by +the rule <quote>must be able to satisfy requests of any size</quote>. +</para> +</listitem> + +<listitem> +<para> +Asynchronous streams of a module may have entirely different sampling +rates. +</para> +</listitem> + +<listitem> +<para> +Outgoing streams: there are explicit functions to allocate packets, to +send packets - and an optional polling mechanism that will tell you when +you should create some more data. +</para> +</listitem> + +<listitem> +<para> +Incoming streams: you get a call when you receive a new packet - you +have to say when you are through with processing all data of that +packet, which must not happen at once (you can say that anytime later, +and if everybody has processed a packet, it will be freed/reused) +</para> +</listitem> +</itemizedlist> + +<para> +When you declare streams, you use the keyword <quote>async</quote> to +indicate you want to make an asynchronous stream. So, for instance, +assume you want to convert an asynchronous stream of bytes into a +synchronous stream of samples. Your interface could look like this: +</para> + +<programlisting> +interface ByteStreamToAudio : SynthModule { + async in byte stream indata; // the asynchronous input sample stream + + out audio stream left,right; // the synchronous output sample streams +}; +</programlisting> + +</sect2> + +<sect2 id="async-streams"> +<title>Using Asynchronous Streams</title> + +<para> +Suppose you decided to write a module to produce sound +asynchronously. Its interface could look like this: +</para> + +<programlisting> +interface SomeModule : SynthModule +{ + async out byte stream outdata; +}; +</programlisting> + +<para> +How do you send the data? The first method is called <quote>push +delivery</quote>. With asynchronous streams you send the data as +packets. That means you send individual packets with bytes as in the +above example. The actual process is: allocate a packet, fill it, send +it. +</para> + +<para> +Here it is in terms of code. First we allocate a packet: +</para> + +<programlisting> +DataPacket<mcopbyte> *packet = outdata.allocPacket(100); +</programlisting> + +<para> +The we fill it: +</para> + +<programlisting> +// cast so that fgets is happy that it has a (char *) pointer +char *data = (char *)packet->contents; + +// as you can see, you can shrink the packet size after allocation +// if you like +if(fgets(data,100,stdin)) + packet->size = strlen(data); +else + packet->size = 0; +</programlisting> + +<para> +Now we send it: +</para> + +<programlisting> +packet->send(); +</programlisting> + +<para> +This is quite simple, but if we want to send packets exactly as fast as +the receiver can process them, we need another approach, the <quote>pull +delivery</quote> method. You ask to send packets as fast as the receiver +is ready to process them. You start with a certain amount of packets you +send. As the receiver processes one packet after another, you start +refilling them with fresh data, and send them again. +</para> + +<para> +You start that by calling setPull. For example: +</para> + +<programlisting> +outdata.setPull(8, 1024); +</programlisting> + +<para> +This means that you want to send packets over outdata. You want to start +sending 8 packets at once, and as the receiver processes some of them, +you want to refill them. +</para> + +<para> +Then, you need to implement a method which fills the packets, which could +look like this: +</para> + +<programlisting> +void request_outdata(DataPacket<mcopbyte> *packet) +{ + packet->size = 1024; // shouldn't be more than 1024 + for(int i = 0;i < 1024; i++) + packet->contents[i] = (mcopbyte)'A'; + packet->send(); +} +</programlisting> + +<para> +Thats it. When you don't have any data any more, you can start sending +packets with zero size, which will stop the pulling. +</para> + +<para> +Note that it is essential to give the method the exact name +<methodname>request_<replaceable>streamname</replaceable></methodname>. +</para> + +<para> +We just discussed sending data. Receiving data is much much +simpler. Suppose you have a simple ToLower filter, which simply converts +all letters in lowercase: +</para> + +<programlisting> +interface ToLower { + async in byte stream indata; + async out byte stream outdata; +}; +</programlisting> + +<para> +This is really simple to implement; here is the whole implementation: +</para> + +<programlisting> +class ToLower_impl : public ToLower_skel { +public: + void process_indata(DataPacket<mcopbyte> *inpacket) + { + DataPacket<mcopbyte> *outpacket = outdata.allocPacket(inpacket->size); + + // convert to lowercase letters + char *instring = (char *)inpacket->contents; + char *outstring = (char *)outpacket->contents; + + for(int i=0;i<inpacket->size;i++) + outstring[i] = tolower(instring[i]); + + inpacket->processed(); + outpacket->send(); + } +}; + +REGISTER_IMPLEMENTATION(ToLower_impl); +</programlisting> + +<para> +Again, it is essential to name the method +<methodname>process_<replaceable>streamname</replaceable></methodname>. +</para> + +<para> +As you see, for each arriving packet you get a call for a function (the +<function>process_indata</function> call in our case). You need to call +the <methodname>processed()</methodname> method of a packet to indicate +you have processed it. +</para> + +<para> +Here is an implementation tip: if processing takes longer (&ie; if you +need to wait for soundcard output or something like that), don't call +processed immediately, but store the whole data packet and call +processed only as soon as you really processed that packet. That way, +senders have a chance to know how long it really takes to do your work. +</para> + +<para> +As synchronization isn't so nice with asynchronous streams, you should +use synchronous streams wherever possible, and asynchronous streams only +when necessary. +</para> + +</sect2> + +<sect2 id="default-streams"> +<title>Default Streams</title> + +<para> +Suppose you have 2 objects, for example an AudioProducer and an +AudioConsumer. The AudioProducer has an output stream and AudioConsumer +has an input one. Each time you want to connect them, you will use those +2 streams. The first use of defaulting is to enable you to make the +connection without specifying the ports in that case. +</para> + +<para> +Now suppose the teo objects above can handle stereo, and each have a +<quote>left</quote> and <quote>right</quote> port. You'd still like to +connect them as easily as before. But how can the connecting system +know which output port to connect to which input port? It has no way to +correctly map the streams. Defaulting is then used to specify several +streams, with an order. Thus, when you connect an object with 2 default +output streams to another one with 2 default input streams, you don't +have to specify the ports, and the mapping will be done correctly. +</para> + +<para> +Of course, this is not limited to stereo. Any number of streams can be +made default if needed, and the connect function will check that the +number of defaults for 2 object match (in the required direction) if you +don't specify the ports to use. +</para> + +<para> +The syntax is as follows: in the &IDL;, you can use the default keyword +in the stream declaration, or on a single line. For example: +</para> + +<programlisting> +interface TwoToOneMixer { + default in audio stream input1, input2; + out audio stream output; +}; +</programlisting> + +<para> +In this example, the object will expect its two input ports to be +connected by default. The order is the one specified on the default +line, so an object like this one: +</para> + +<programlisting> +interface DualNoiseGenerator { + out audio stream bzzt, couic; + default couic, bzzt; +}; +</programlisting> + +<para> +Will make connections from <quote>couic</quote> to +<quote>input1</quote>, and <quote>bzzt</quote> to <quote>input2</quote> +automatically. Note that since there is only one output for the mixer, +it will be made default in this case (see below). The syntax used in the +noise generator is useful to declare a different order than the +declaration, or selecting only a few ports as default. The directions of +the ports on this line will be looked up by &mcopidl;, so don't specify +them. You can even mix input and output ports in such a line, only the +order is important. +</para> + +<para> +There are some rules that are followed when using inheritance: +</para> + +<itemizedlist> +<listitem> +<para> +If a default list is specified in the &IDL;, then use +it. Parent ports can be put in this list as well, whether they were +default in the parent or not. +</para> +</listitem> + +<listitem> +<para> +Otherwise, inherit parent's defaults. Ordering is parent1 default1, +parent1 default2..., parent2 default1... If there is a common ancestor +using 2 parent branches, a <quote>virtual public</quote>-like merging is +done at that default's first occurrence in the list. +</para> +</listitem> + +<listitem> +<para> +If there is still no default and a single stream in a +direction, use it as default for that direction. +</para> +</listitem> +</itemizedlist> + +</sect2> + +</sect1> +<sect1 id="attribute-change-notify"> +<title>Attribute change notifications</title> + +<!-- TODO: This should be embedded better into the context - I mean: the + context should be written ;-). --> + +<para> +Attribute change notifications are a way to know when an attribute +changed. They are a bit comparable with &Qt;'s or Gtk's signals and +slots. For instance, if you have a &GUI; element, a slider, which +configures a number between 0 and 100, you will usually have an object +that does something with that number (for instance, it might be +controlling the volume of some audio signal). So you would like that +whenever the slider is moved, the object which scales the volume gets +notified. A connection between a sender and a receiver. +</para> + +<para> +&MCOP; deals with that by being able to providing notifications when +attributes change. Whatever is declared as <quote>attribute</quote> in +the &IDL;, can emit such change notifications, and should do so, +whenever it is modified. Whatever is declared as +<quote>attribute</quote> can also receive such change notifications. So +for instance if you had two &IDL; interfaces, like these: +</para> + +<programlisting> + interface Slider { + attribute long min,max; + attribute long position; + }; + interface VolumeControl : Arts::StereoEffect { + attribute long volume; // 0..100 + }; +</programlisting> + +<para> +You can connect them using change notifications. It works using the +normal flowsystem connect operation. In this case, the C++ code to +connect two objects would look like this: +</para> + +<programlisting> +#include <connect.h> +using namespace Arts; +[...] +connect(slider,"position_changed",volumeControl,"volume"); +</programlisting> + +<para> +As you see, each attribute offers two different streams, one for sending +the change notifications, called +<function><replaceable>attributename</replaceable>_changed</function>, + +<!-- TODO - how do I markup code that is an example - you wouldn't write + attributename in the source, but the name of some attribute + + LW: I'm guessing + here, because I know how to markup QT code, but your stuff is different. + Hopefully this will give you inspiration, and we can work out later the fine + tuning if I have it wrong. The line above in the code sample, if it were qt + stuff, I would mark up this way (linebreaks for clarity of markup only, yes I + know it's incorrect!): + + <function>connect(<classname>slider</classname>, + <function><replaceable>position</replaceable>_changed</function>, + <classname>volumeControl</classname>, + <function>volume</function>);</function> + + You can use <function><replaceable>attributename</function> and even + <function><replaceable>attributename</replaceable>_changed</function>. + + If I have the above totally wrong (which is entirely possible!) Some other + elements you might find handy: + + <varname>, <type>, <returnvalue>, <constant>, <methodname> + There's also a markup guide at http://madmax.atconnex.net/kde/ that might + help, although unfortunately the programming section is still incomplete. --> + + and one for receiving change notifications, called +<function>attributename</function>. +</para> + +<para> +It is important to know that change notifications and asynchronous +streams are compatible. They are also network transparent. So you can +connect a change notification of a float attribute of a &GUI; widget has +to an asynchronous stream of a synthesis module running on another +computer. This of course also implies that change notifications are +<emphasis>not synchronous</emphasis>, this means, that after you have +sent the change notification, it may take some time until it really gets +received. +</para> + +<sect2 id="sending-change-notifications"> + +<title>Sending change notifications</title> + +<para> +When implementing objects that have attributes, you need to send change +notifications whereever an attribute changes. The code for doing this +looks like this: +</para> + +<programlisting> + void KPoti_impl::value(float newValue) + { + if(newValue != _value) + { + _value = newValue; + value_changed(newValue); // <- send change notification + } + } +</programlisting> + +<para> +It is strongly recommended to use code like this for all objects you +implement, so that change notifications can be used by other people. You +should however void sending notifications too often, so if you are doing +signal processing, it is probably the best if you keep track when you +sent your last notification, so that you don't send one with every +sample you process. +</para> + +</sect2> + +<sect2 id="change-notifications-apps"> +<title>Applications for change notifications</title> + +<para> +It will be especially useful to use change notifications in conjunction +with scopes (things that visualize audio data for instance), gui +elements, control widgets, and monitoring. Code using this is in +<filename class="directory">kdelibs/arts/tests</filename>, and in the +experimental artsgui implementation, which you can find under <filename +class="directory">kdemultimedia/arts/gui</filename>. +</para> + +<!-- TODO: can I markup links into the source code - if yes, how? --> + +<!-- LW: Linking into the source is problematic - we can't assume people are +reading this on a machine with the sources available, or that they aren't +reading it from a website. We're working on it! --> + +</sect2> +</sect1> + +<sect1 id="the-mcoprc-file"> + +<title>The <literal role="extension">.mcoprc</literal> file</title> + +<para> +The <literal role="extension">.mcoprc</literal> file (in each user's +home folder) can be used to configure &MCOP; in some ways. Currently, +the following is possible: +</para> + +<variablelist> + +<varlistentry> +<term>GlobalComm</term> +<listitem> +<para> +The name of an interface to be used for global communication. Global +communication is used to find other objects and obtain the secret +cookie. Multiple &MCOP; clients/servers that should be able to talk to +each other need to have a GlobalComm object which is able to share +information between them. Currently, the possible values are +<quote>Arts::TmpGlobalComm</quote> to communicate via <filename +class="directory">/tmp/mcop-<replaceable>username</replaceable></filename> +folder (which will only work on the local computer) and +<quote>Arts::X11GlobalComm</quote> to communicate via the root window +properties on the X11 server. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>TraderPath</term> + +<listitem> +<para> +Specifies where to look for trader information. You can list more than +one folder here, and separate them with commas, like +</para> +</listitem> + +</varlistentry> + +<varlistentry> +<term>ExtensionPath</term> + +<listitem> +<para> +Specifies from which folders extensions (in the form of shared +libraries) are loaded. Multiple values can be specified comma separated. +</para> +</listitem> + +</varlistentry> +</variablelist> + +<para> +An example which uses all of the above is: +</para> + +<programlisting> +# $HOME/.mcoprc file +GlobalComm=Arts::X11GlobalComm + +# if you are a developer, it might be handy to add a folder in your home +# to the trader/extension path to be able to add components without +# installing them +TraderPath="/opt/kde2/lib/mcop","/home/joe/mcopdevel/mcop" +ExtensionPath="/opt/kde2/lib","/home/joe/mcopdevel/lib" +</programlisting> + +</sect1> + +<sect1 id="mcop-for-corba-users"> +<title>&MCOP; for <acronym>CORBA</acronym> Users</title> + +<para> +If you have used <acronym>CORBA</acronym> before, you will see that +&MCOP; is much the same thing. In fact, &arts; prior to version 0.4 used +<acronym>CORBA</acronym>. +</para> + +<para> +The basic idea of <acronym>CORBA</acronym> is the same: you implement +objects (components). By using the &MCOP; features, your objects are not +only available as normal classes from the same process (via standard C++ +techniques) - they also are available to remote servers +transparently. For this to work, the first thing you need to do is to +specify the interface of your objects in an &IDL; file - just like +<acronym>CORBA</acronym> &IDL;. There are only a few differences. +</para> + +<sect2 id="corba-missing"> +<title><acronym>CORBA</acronym> Features That Are Missing In +&MCOP;</title> + +<para> +In &MCOP; there are no <quote>in</quote> and <quote>out</quote> +parameters on method invocations. Parameters are always incoming, the +return code is always outgoing, which means that the interface: +</para> + +<programlisting> +// CORBA idl +interface Account { + void deposit( in long amount ); + void withdraw( in long amount ); + long balance(); +}; +</programlisting> + +<para> +is written as +</para> + +<programlisting> +// MCOP idl +interface Account { + void deposit( long amount ); + void withdraw( long amount ); + long balance(); +}; +</programlisting> + +<para> +in &MCOP;. +</para> + +<para> +There is no exception support. &MCOP; doesn't have exceptions - it uses +something else for error handling. +</para> + +<para> +There are no union types and no typedefs. I don't know if that is a real +weakness, something one would desperately need to survive. +</para> + +<para> +There is no support for passing interfaces or object references +</para> + +</sect2> + +<sect2 id="corba-different"> +<title><acronym>CORBA</acronym> Features That Are Different In +&MCOP;</title> + +<para> +You declare sequences as +<quote>sequence<replaceable>type</replaceable></quote> in &MCOP;. There +is no need for a typedef. For example, instead of: +</para> + +<programlisting> +// CORBA idl +struct Line { + long x1,y1,x2,y2; +}; +typedef sequence<Line> LineSeq; +interface Plotter { + void draw(in LineSeq lines); +}; +</programlisting> + +<para> +you would write +</para> + +<programlisting> +// MCOP idl +struct Line { + long x1,y1,x2,y2; +}; +interface Plotter { + void draw(sequence<Line> lines); +}; +</programlisting> + +</sect2> + +<sect2 id="no-in-corba"> +<title>&MCOP; Features That Are Not In <acronym>CORBA</acronym></title> + +<para> +You can declare streams, which will then be evaluated by the &arts; +framework. Streams are declared in a similar manner to attributes. For +example: +</para> + +<programlisting> +// MCOP idl +interface Synth_ADD : SynthModule { + in audio stream signal1,signal2; + out audio stream outvalue; +}; +</programlisting> + +<para> +This says that your object will accept two incoming synchronous audio +streams called signal1 and signal2. Synchronous means that these are +streams that deliver x samples per second (or other time), so that the +scheduler will guarantee to always provide you a balanced amount of +input data (⪚ 200 samples of signal1 are there and 200 samples +signal2 are there). You guarantee that if your object is called with +those 200 samples signal1 + signal2, it is able to produce exactly 200 +samples to outvalue. +</para> + +</sect2> + +<sect2 id="mcop-binding"> +<title>The &MCOP; C++ Language Binding</title> + +<para> +This differs from <acronym>CORBA</acronym> mostly: +</para> + +<itemizedlist> +<listitem> +<para> +Strings use the C++ <acronym>STL</acronym> <classname>string</classname> +class. When stored in sequences, they are stored <quote>plain</quote>, +that means they are considered to be a primitive type. Thus, they need +copying. +</para> +</listitem> + +<listitem> +<para> +longs are plain long's (expected to be 32 bit). +</para> +</listitem> + +<listitem> +<para> +Sequences use the C++ <acronym>STL</acronym> +<classname>vector</classname> class. +</para> +</listitem> + +<listitem> +<para> +Structures are all derived from the &MCOP; class +<classname>Type</classname>, and generated by the &MCOP; &IDL; +compiler. When stored in sequences, they are not stored +<quote>plain</quote> , but as pointers, as otherwise, too much copying +would occur. +</para> +</listitem> +</itemizedlist> +</sect2> + +<sect2 id="implementing-objects"> +<title>Implementing &MCOP; Objects</title> + +<para> +After having them passed through the &IDL; compiler, you need to derive +from the <classname>_skel</classname> class. For instance, consider you +have defined your interface like this: +</para> + +<programlisting> +// MCOP idl: hello.idl +interface Hello { + void hello(string s); + string concat(string s1, string s2); + long sum2(long a, long b); +}; +</programlisting> + +<para> +You pass that through the &IDL; compiler by calling +<userinput><command>mcopidl</command> +<parameter>hello.idl</parameter></userinput>, which will in turn generate +<filename>hello.cc</filename> and <filename>hello.h</filename>. To +implement it, you need to define a C++-class that inherits the skeleton: +</para> + +<programlisting> +// C++ header file - include hello.h somewhere +class Hello_impl : virtual public Hello_skel { +public: + void hello(const string& s); + string concat(const string& s1, const string& s2); + long sum2(long a, long b); +}; +</programlisting> + +<para> +Finally, you need to implement the methods as normal C++ +</para> + +<programlisting> +// C++ implementation file + +// as you see string's are passed as const string references +void Hello_impl::hello(const string& s) +{ + printf("Hello '%s'!\n",s.c_str()); +} + +// when they are a returncode they are passed as "normal" strings +string Hello_impl::concat(const string& s1, const string& s2) +{ + return s1+s2; +} + +long Hello_impl::sum2(long a, long b) +{ + return a+b; +} +</programlisting> + +<para> +Once you do that, you have an object which can communicate using &MCOP;. +Just create one (using the normal C++ facilities to create an object): +</para> + +<programlisting> + Hello_impl server; +</programlisting> + +<para> +And as soon as you give somebody the reference +</para> + +<programlisting> + string reference = server._toString(); + printf("%s\n",reference.c_str()); +</programlisting> + +<para> +and go to the &MCOP; idle loop +</para> + +<programlisting> +Dispatcher::the()->run(); +</programlisting> + +<para> +People can access the thing using +</para> + +<programlisting> +// this code can run anywhere - not necessarily in the same process +// (it may also run on a different computer/architecture) + + Hello *h = Hello::_fromString([the object reference printed above]); +</programlisting> + +<para> +and invoke methods: +</para> + +<programlisting> + if(h) + h->hello("test"); + else + printf("Access failed?\n"); +</programlisting> + +</sect2> +</sect1> + +<sect1 id="mcop-security"> +<title>&MCOP; Security Considerations</title> + +<para> +Since &MCOP; servers will listen on a <acronym>TCP</acronym> port, +potentially everybody (if you are on the Internet) may try to connect +&MCOP; services. Thus, it is important to authenticate clients. &MCOP; +uses the md5-auth protocol. +</para> + +<para> +The md5-auth protocol does the following to ensure that only selected +(trusted) clients may connect to a server: +</para> + +<itemizedlist> +<listitem> +<para> +It assumes you can give every client a secret cookie. +</para> +</listitem> + +<listitem> +<para> +Every time a client connects, it verifies that this client knows that +secret cookie, without actually transferring it (not even in a form that +somebody listening to the network traffic could find it out). +</para> +</listitem> + +</itemizedlist> + +<para> +To give each client the secret cookie, &MCOP; will (normally) put it in +the <filename class="directory">mcop</filename> folder (under +<filename +class="directory">/tmp/mcop-<envar>USER</envar>/secret-cookie</filename>). Of +course, you can copy it to other computers. However, if you do so, use a +secure transfer mechanism, such as <command>scp</command> (from +<application>ssh</application>). +</para> + +<para> +The authentication of clients uses the following steps: +</para> + +<procedure> +<step> +<para> +[SERVER] generate a new (random) cookie R +</para> +</step> + +<step> +<para> +[SERVER] send it to the client +</para> +</step> + +<step> +<para> +[CLIENT] read the "secret cookie" S from a file +</para> +</step> + +<step> +<para> +[CLIENT] mangle the cookies R and S to a mangled cookie M using the MD5 +algorithm +</para> +</step> + +<step> +<para> +[CLIENT] send M to the server +</para> +</step> + +<step> +<para> +[SERVER] verify that mangling R and S gives just the +same thing as the cookie M received from the client. If yes, +authentication is successful. +</para> +</step> + +</procedure> + +<para> +This algorithm should be secure, given that +</para> + +<orderedlist> +<listitem> +<para> +The secret cookies and random cookies are <quote>random enough</quote> + and +</para> +</listitem> + +<listitem> +<para> +The MD5 hashing algorithm doesn't allow to find out the +<quote>original text</quote>, that is the secret cookie S and the random +cookie R (which is known, anyway), from the mangled cookie M. +</para> +</listitem> +</orderedlist> + +<para> +The &MCOP; protocol will start every new connection with an +authentication process. Basically, it looks like this: +</para> + +<procedure> + +<step> +<para> +Server sends a ServerHello message, which describes +the known authentication protocols. +</para> +</step> + +<step> +<para> +Client sends a ClientHello message, which includes authentication info. +</para> +</step> + +<step> +<para> +Server sends an AuthAccept message. +</para> +</step> +</procedure> + +<para> +To see that the security actually works, we should look at how messages +are processed on unauthenticated connections: +</para> + +<itemizedlist> +<listitem> +<para> +Before the authentication succeeds, the server will not receive other +messages from the connection. Instead, if the server for instance +expects a <quote>ClientHello</quote> message, and gets an mcopInvocation +message, it will drop the connection. +</para> +</listitem> + +<listitem> +<para> +If the client doesn't send a valid &MCOP; message at all (no &MCOP; +magic in the message header) in the authentication phase, but something +else, the connection is dropped. +</para> +</listitem> + +<listitem> +<para> +If the client tries to send a very very large message (> 4096 bytes +in the authentication phase, the message size is truncated to 0 bytes, +which will cause that it isn't accepted for authentication) This is to +prevent unauthenticated clients from sending ⪚ 100 megabytes of +message, which would be received and could cause the server to run out +of memory. +</para> +</listitem> + +<listitem> +<para> +If the client sends a corrupt ClientHello message (one, for which +demarshalling fails), the connection is dropped. +</para> +</listitem> + +<listitem> +<para> +If the client send nothing at all, then a timeout should occur (to be +implemented). +</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="mcop-protocol"> +<title>&MCOP; Protocol Specification</title> + +<sect2 id="mcop-protocol-intro"> +<title>Introduction</title> + +<para> +It has conceptual similarities to <acronym>CORBA</acronym>, but it is +intended to extend it in all ways that are required for real time +multimedia operations. +</para> + +<para> +It provides a multimedia object model, which can be used for both: +communication between components in one address space (one process), and +between components that are in different threads, processes or on +different hosts. +</para> + +<para> +All in all, it will be designed for extremely high performance (so +everything shall be optimized to be blazingly fast), suitable for very +communicative multimedia applications. For instance streaming videos +around is one of the applications of &MCOP;, where most +<acronym>CORBA</acronym> implementations would go down to their knees. +</para> + +<para> +The interface definitions can handle the following natively: +</para> + +<itemizedlist> +<listitem> +<para> +Continuous streams of data (such as audio data). +</para> +</listitem> + +<listitem> +<para> +Event streams of data (such as &MIDI; events). +</para> +</listitem> + +<listitem> +<para> +Real reference counting. +</para> +</listitem> +</itemizedlist> + +<para> +and the most important <acronym>CORBA</acronym> gimmicks, like +</para> + +<itemizedlist> +<listitem> +<para> +Synchronous method invocations. +</para> +</listitem> + +<listitem> +<para> +Asynchronous method invocations. +</para> +</listitem> + +<listitem> +<para> +Constructing user defined data types. +</para> +</listitem> + +<listitem> +<para> +Multiple inheritance. +</para> +</listitem> + +<listitem> +<para> +Passing object references. +</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="mcop-protocol-marshalling"> +<title>The &MCOP; Message Marshalling</title> + +<para> +Design goals/ideas: +</para> + +<itemizedlist> + +<listitem> +<para> +Marshalling should be easy to implement. +</para> +</listitem> + +<listitem> +<para> +Demarshalling requires the receiver to know what type he wants to +demarshall. +</para> +</listitem> + +<listitem> +<para> +The receiver is expected to use every information - so skipping is only +in the protocol to a degree that: +</para> + +<itemizedlist> +<listitem> +<para> +If you know you are going to receive a block of bytes, you don't need to +look at each byte for an end marker. +</para> +</listitem> + +<listitem> +<para> +If you know you are going to receive a string, you don't need to read it +until the zero byte to find out it's length while demarshalling, however, +</para> +</listitem> + +<listitem> +<para> +If you know you are going to receive a sequence of strings, you need to +look at the length of each of them to find the end of the sequence, as +strings have variable length. But if you use the strings for something +useful, you'll need to do that anyway, so this is no loss. +</para> +</listitem> +</itemizedlist> + +</listitem> + +<listitem> +<para> +As little overhead as possible. +</para> +</listitem> +</itemizedlist> + +<!-- TODO: Make this a table --> + +<para> +Marshalling of the different types is show in the table below: +</para> + +<informaltable> +<tgroup cols="3"> +<thead> +<row> +<entry>Type</entry> +<entry>Marshalling Process</entry> +<entry>Result</entry> +</row> +</thead> + +<tbody> +<row> +<entry><type>void</type></entry> +<entry><type>void</type> types are marshalled by omitting them, so +nothing is written to the stream for them.</entry> +<entry></entry> +</row> + +<row> +<entry><type>long</type></entry> +<entry>is marshalled as four bytes, the most significant byte first, +so the number 10001025 (which is 0x989a81) would be marshalled +as:</entry> +<entry><literal>0x00 0x98 0x9a 0x81</literal></entry> +</row> + +<row> +<entry><type>enums</type></entry> +<entry><para>are marshalled like <type>long</type>s</para></entry> +<entry></entry> +</row> + +<row> +<entry><type>byte</type></entry> +<entry><para>is marshalled as a single byte, so the byte 0x42 would be +marshalled as:</para></entry> +<entry><literal>0x42</literal></entry> +</row> + +<row> +<entry><type>string</type></entry> +<entry><para>is marshalled as a <type>long</type>, containing the length +of the following string, and then the sequence of characters strings +must end with one zero byte (which is included in the length +counting).</para> +<important> +<para>include the trailing 0 byte in length counting!</para> +</important> +<para><quote>hello</quote> would be marshalled as:</para></entry> +<entry><literal>0x00 0x00 0x00 0x06 0x68 0x65 0x6c 0x6c 0x6f 0x00</literal></entry> +</row> + +<row> +<entry><type>boolean</type></entry> +<entry><para>is marshalled as a byte, containing 0 if +<returnvalue>false</returnvalue> or 1 if +<returnvalue>true</returnvalue>, so the boolean value +<returnvalue>true</returnvalue> is marshalled as:</para></entry> +<entry><literal>0x01</literal></entry> +</row> + +<row> +<entry><type>float</type></entry> +<entry><para>is marshalled after the four byte IEEE754 representation - +detailed docs how IEEE works are here: <ulink +url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink> +and here: <ulink +url="http://java.sun.com/docs/books/vmspec/2nd-edition/html/Overview.doc.html">http://java.sun.com/docs/books/vmspec/2nd-edition/html/Overview.doc.html</ulink>. +So, the value 2.15 would be marshalled as:</para></entry> +<entry><literal>0x9a 0x99 0x09 0x40</literal></entry> +</row> + +<row> +<entry><type>struct</type></entry> +<entry><para>A structure is marshalled by marshalling it's +contents. There are no additional prefixes or suffixes required, so the +structure +</para> +<programlisting> +struct test { + string name; // which is "hello" + long value; // which is 10001025 (0x989a81) +}; +</programlisting> +<para>would be marshalled as</para></entry> +<entry> +<literallayout> +0x00 0x00 0x00 0x06 0x68 0x65 0x6c 0x6c +0x6f 0x00 0x00 0x98 0x9a 0x81 +</literallayout></entry> +</row> + +<row> +<entry><type>sequence</type></entry> +<entry><para>a sequence is marshalled by listing the number of elements +that follow, and then marshalling the elements one by one.</para> +<para>So a sequence of 3 longs a, with a[0] = 0x12345678, a[1] = 0x01 +and a[2] = 0x42 would be marshalled as:</para></entry> +<entry> +<literallayout> +0x00 0x00 0x00 0x03 0x12 0x34 0x56 0x78 +0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x42 +</literallayout> +</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +If you need to refer to a type, all primitive types are referred by the +names given above. Structures and enums get own names (like +Header). Sequences are referred as *<replaceable>normal +type</replaceable>, so that a sequence of longs is <quote>*long</quote> +and a sequence of Header struct's is <quote>*Header</quote>. +</para> + +</sect2> + +<sect2 id="mcop-protocol-messages"> +<title>Messages</title> + +<para> +The &MCOP; message header format is defined as defined by this +structure: +</para> + +<programlisting> +struct Header { + long magic; // the value 0x4d434f50, which is marshalled as MCOP + long messageLength; + long messageType; +}; +</programlisting> + +<para> +The possible messageTypes are currently +</para> + +<programlisting> + mcopServerHello = 1 + mcopClientHello = 2 + mcopAuthAccept = 3 + mcopInvocation = 4 + mcopReturn = 5 + mcopOnewayInvocation = 6 +</programlisting> + +<para> +A few notes about the &MCOP; messaging: +</para> + + +<itemizedlist> +<listitem> +<para> +Every message starts with a Header. +</para> +</listitem> + +<listitem> +<para> +Some messages types should be dropped by the server, as long as the +authentication is not complete. +</para> +</listitem> + +<listitem> +<para> +After receiving the header, the protocol (connection) handling can +receive the message completely, without looking at the contents. +</para> +</listitem> +</itemizedlist> + +<para> +The messageLength in the header is of course in some cases redundant, +which means that this approach is not minimal regarding the number of +bytes. +</para> + +<para> +However, it leads to an easy (and fast) implementation of non-blocking +messaging processing. With the help of the header, the messages can be +received by protocol handling classes in the background (non-blocking), +if there are many connections to the server, all of them can be served +parallel. You don't need to look at the message content, to receive the +message (and to determine when you are done), just at the header, so the +code for that is pretty easy. +</para> + +<para> +Once a message is there, it can be demarshalled and processed in one +single pass, without caring about cases where not all data may have been +received (because the messageLength guarantees that everything is +there). +</para> + +</sect2> + +<sect2 id="mcop-protocol-invocations"> +<title>Invocations</title> + +<para> +To call a remote method, you need to send the following structure in the +body of an &MCOP; message with the messageType = 1 (mcopInvocation): +</para> + +<programlisting> +struct Invocation { + long objectID; + long methodID; + long requestID; +}; +</programlisting> + +<para> +after that, you send the parameters as structure, ⪚ if you invoke the +method string concat(string s1, string s2), you send a structure like +</para> + +<programlisting> +struct InvocationBody { + string s1; + string s2; +}; +</programlisting> + + +<para> +if the method was declared to be oneway - that means asynchronous +without return code - then that was it. Otherwise, you'll receive as +answer the message with messageType = 2 (mcopReturn) +</para> + +<programlisting> +struct ReturnCode { + long requestID; + <resulttype> result; +}; +</programlisting> + + +<para> +where <resulttype> is the type of the result. As void types are +omitted in marshalling, you can also only write the requestID if you +return from a void method. +</para> + +<para> +So our string concat(string s1, string s2) would lead to a returncode +like +</para> + +<programlisting> +struct ReturnCode { + long requestID; + string result; +}; +</programlisting> + +</sect2> + +<sect2 id="mcop-protocol-inspecting"> +<title>Inspecting Interfaces</title> + +<para> +To do invocations, you need to know the methods an object supports. To +do so, the methodID 0, 1, 2 and 3 are hardwired to certain +functionalities. That is +</para> + +<programlisting> +long _lookupMethod(MethodDef methodDef); // methodID always 0 +string _interfaceName(); // methodID always 1 +InterfaceDef _queryInterface(string name); // methodID always 2 +TypeDef _queryType(string name); // methodID always 3 +</programlisting> + +<para> +to read that, you of course need also +</para> + +<programlisting> +struct MethodDef { + string methodName; + string type; + long flags; // set to 0 for now (will be required for streaming) + sequence<ParamDef> signature; +}; + +struct ParamDef { + string name; + long typeCode; +}; +</programlisting> + +<para> +the parameters field contains type components which specify the types of +the parameters. The type of the returncode is specified in the +MethodDef's type field. +</para> + +<para> +Strictly speaking, only the methods +<methodname>_lookupMethod()</methodname> and +<methodname>_interfaceName()</methodname> differ from object to object, +while the <methodname>_queryInterface()</methodname> and +<methodname>_queryType()</methodname> are always the same. +</para> + +<para> +What are those methodIDs? If you do an &MCOP; invocation, you are +expected to pass a number for the method you are calling. The reason for +that is, that numbers can be processed much faster than strings when +executing an &MCOP; request. +</para> + +<para> +So how do you get those numbers? If you know the signature of the +method, that is a MethodDef that describes the method, (which contains +name, type, parameter names, parameter types and such), you can pass +that to _lookupMethod of the object where you wish to call a method. As +_lookupMethod is hardwired to methodID 0, you should encounter no +problems doing so. +</para> + +<para> +On the other hand, if you don't know the method signature, you can find +which methods are supported by using _interfaceName, _queryInterface and +_queryType. +</para> +</sect2> + +<sect2 id="mcop-protocol-typedefs"> +<title>Type Definitions</title> + +<para> +User defined datatypes are described using the +<structname>TypeDef</structname> structure: +</para> + +<programlisting> +struct TypeComponent { + string type; + string name; +}; + +struct TypeDef { + string name; + + sequence<TypeComponent> contents; +}; +</programlisting> + +</sect2> +</sect1> + +<sect1 id="why-not-dcop"> +<title>Why &arts; Doesn't Use &DCOP;</title> + +<para> +Since &kde; dropped <acronym>CORBA</acronym> completely, and is using +&DCOP; everywhere instead, naturally the question arises why &arts; +isn't doing so. After all, &DCOP; support is in +<classname>KApplication</classname>, is well-maintained, supposed to +integrate greatly with libICE, and whatever else. +</para> + +<para> +Since there will be (potentially) a lot of people asking whether having +&MCOP; besides &DCOP; is really necessary, here is the answer. Please +don't get me wrong, I am not trying to say <quote>&DCOP; is +bad</quote>. I am just trying to say <quote>&DCOP; isn't the right +solution for &arts;</quote> (while it is a nice solution for other +things). +</para> + +<para> +First, you need to understand what exactly &DCOP; was written +for. Created in two days during the &kde;-TWO meeting, it was intended +to be as simple as possible, a really <quote>lightweight</quote> +communication protocol. Especially the implementation left away +everything that could involve complexity, for instance a full blown +concept how data types shall be marshalled. +</para> + +<para> +Even although &DCOP; doesn't care about certain things (like: how do I +send a string in a network-transparent manner?) - this needs to be +done. So, everything that &DCOP; doesn't do, is left to &Qt; in the +&kde; apps that use &DCOP; today. This is mostly type management (using +the &Qt; serialization operator). +</para> + +<para> +So &DCOP; is a minimal protocol which perfectly enables &kde; +applications to send simple messages like <quote>open a window pointing +to http://www.kde.org</quote> or <quote>your configuration data has +changed</quote>. However, inside &arts; the focus lies on other things. +</para> + +<para> +The idea is, that little plugins in &arts; will talk involving such data +structures as <quote>midi events</quote> and <quote>songposition +pointers</quote> and <quote>flow graphs</quote>. +</para> + +<para> +These are complex data types, which must be sent between different +objects, and be passed as streams, or parameters. &MCOP; supplies a type +concept, to define complex data types out of simpler ones (similar to +structs or arrays in C++). &DCOP; doesn't care about types at all, so +this problem would be left to the programmer - like: writing C++ classes +for the types, and make sure they can serialize properly (for instance: +support the &Qt; streaming operator). +</para> + +<para> +But that way, they would be inaccessible to everything but direct C++ +coding. Specifically, you could not design a scripting language, that +would know all types plugins may ever expose, as they are not self +describing. +</para> + +<para> +Much the same argument is valid for interfaces as well. &DCOP; objects +don't expose their relationships, inheritance hierarchies, etc. - if you +were to write an object browser which shows you <quote>what attributes +has this object got</quote>, you'd fail. +</para> + + +<para> +While Matthias told me that you have a special function +<quote>functions</quote> on each object that tells you about the methods +that an object supports, this leaves out things like attributes +(properties), streams and inheritance relations. +</para> + +<para> +This seriously breaks applications like &arts-builder;. But remember: +&DCOP; was not so much intended to be an object model (as &Qt; already +has one with <application>moc</application> and similar), nor to be +something like <acronym>CORBA</acronym>, but to supply inter-application +communication. +</para> + +<para> +Why &MCOP; even exists is: it should work fine with streams between +objects. &arts; makes heavily use of small plugins, which interconnect +themselves with streams. The <acronym>CORBA</acronym> version of &arts; +had to introduce a very annoying split between <quote>the SynthModule +objects</quote>, which were the internal work modules that did do the +streaming, and <quote>the <acronym>CORBA</acronym> interface</quote>, +which was something external. +</para> + +<para> +Much code cared about making interaction between <quote>the SynthModule +objects</quote> and <quote>the <acronym>CORBA</acronym> +interface</quote> look natural, but it didn't, because +<acronym>CORBA</acronym> knew nothing at all about streams. &MCOP; +does. Look at the code (something like +<filename>simplesoundserver_impl.cc</filename>). Way better! Streams +can be declared in the interface of modules, and implemented in a +natural looking way. +</para> + +<para> +One can't deny it. One of the reasons why I wrote &MCOP; was speed. Here +are some arguments why &MCOP; will definitely be faster than &DCOP; +(even without giving figures). +</para> + + +<para> +An invocation in &MCOP; will have a six-<quote>long</quote>-header. That +is: +</para> + +<itemizedlist> +<listitem><para>magic <quote>MCOP</quote></para></listitem> +<listitem><para>message type (invocation)</para></listitem> +<listitem><para>size of the request in bytes</para></listitem> +<listitem><para>request ID</para></listitem> +<listitem><para>target object ID</para></listitem> +<listitem><para>target method ID</para></listitem> +</itemizedlist> + +<para> +After that, the parameters follow. Note that the demarshalling of this +is extremely fast. You can use table lookups to find the object and the +method demarshalling function, which means that complexity is O(1) [ it +will take the same amount of time, no matter how many objects are alive, +or how many functions are there ]. +</para> + +<para> +Comparing this to &DCOP;, you'll see, that there are at least +</para> + +<itemizedlist> +<listitem><para>a string for the target object - something like +<quote>myCalculator</quote></para></listitem> +<listitem><para>a string like <quote>addNumber(int,int)</quote> to +specify the method</para></listitem> +<listitem><para>several more protocol info added by libICE, and other +DCOP specifics I don't know</para></listitem> +</itemizedlist> + +<para> +These are much more painful to demarshall, as you'll need to parse the +string, search for the function, &etc;. +</para> + +<para> +In &DCOP;, all requests are running through a server +(<application>DCOPServer</application>). That means, the process of a +synchronous invocation looks like this: +</para> + +<itemizedlist> +<listitem> +<para> +Client process sends invocation. +</para> +</listitem> + +<listitem> +<para> +<application>DCOPserver</application> (man-in-the-middle) receives +invocation and looks where it needs to go, and sends it to the +<quote>real</quote> server. +</para> +</listitem> + +<listitem> +<para> +Server process receives invocation, performs request and sends result. +</para> +</listitem> + +<listitem> +<para> +<application>DCOPserver</application> (man-in-the-middle) receives +result and ... sends it to the client. +</para> +</listitem> + +<listitem> +<para> +Client decodes reply. +</para> +</listitem> +</itemizedlist> + +<para> +In &MCOP;, the same invocation looks like this: +</para> + +<itemizedlist> +<listitem> +<para> +Client process sends invocation. +</para> +</listitem> + +<listitem> +<para> +Server process receives invocation, performs request and sends result. +</para> +</listitem> + +<listitem> +<para> +Client decodes reply. +</para> +</listitem> +</itemizedlist> + +<para> +Say both were implemented correctly, &MCOP;s peer-to-peer strategy +should be faster by a factor of two, than &DCOP;s man-in-the-middle +strategy. Note however that there were of course reasons to choose the +&DCOP; strategy, which is namely: if you have 20 applications running, +and each app is talking to each app, you need 20 connections in &DCOP;, +and 200 with &MCOP;. However in the multimedia case, this is not +supposed to be the usual setting. +</para> + +<para> +I tried to compare &MCOP; and &DCOP;, doing an invocation like adding +two numbers. I modified testdcop to achieve this. However, the test may +not have been precise on the &DCOP; side. I invoked the method in the +same process that did the call for &DCOP;, and I didn't know how to get +rid of one debugging message, so I used output redirection. +</para> + +<para> +The test only used one object and one function, expect &DCOP;s results +to decrease with more objects and functions, while &MCOP;s results +should stay the same. Also, the <application>dcopserver</application> +process wasn't connected to other applications, it might be that if many +applications are connected, the routing performance decreases. +</para> + +<para> +The result I got was that while &DCOP; got slightly more than 2000 +invocations per second, &MCOP; got slightly more than 8000 invocations +per second. That makes a factor of 4. I know that &MCOP; isn't tuned to +the maximum possible, yet. (Comparison: <acronym>CORBA</acronym>, as +implemented with mico, does something between 1000 and 1500 invocations +per second). +</para> + +<para> +If you want <quote>harder</quote> data, consider writing some small +benchmark app for &DCOP; and send it to me. +</para> + +<para> +<acronym>CORBA</acronym> had the nice feature that you could use objects +you implemented once, as <quote>separate server process</quote>, or as +<quote>library</quote>. You could use the same code to do so, and +<acronym>CORBA</acronym> would transparently decide what to do. With +&DCOP;, that is not really intended, and as far as I know not really +possible. +</para> + +<para> +&MCOP; on the other hand should support that from the beginning. So you +can run an effect inside &artsd;. But if you are a wave editor, you can +choose to run the same effect inside your process space as well. +</para> + +<para> +While &DCOP; is mostly a way to communicate between apps, &MCOP; is also +a way to communicate inside apps. Especially for multimedia streaming, +this is important (as you can run multiple &MCOP; objects parallely, to +solve a multimedia task in your application). +</para> + +<para> +Although &MCOP; does not currently do so, the possibilities are open to +implement quality of service features. Something like <quote>that &MIDI; event +is really really important, compared to this invocation</quote>. Or something +like <quote>needs to be there in time</quote>. +</para> + +<para> +On the other hand, stream transfer can be integrated in the &MCOP; +protocol nicely, and combined with <acronym>QoS</acronym> stuff. Given +that the protocol may be changed, &MCOP; stream transfer should not +really get slower than conventional <acronym>TCP</acronym> streaming, +but: it will be easier and more consistent to use. +</para> + +<para> +There is no need to base a middleware for multimedia on &Qt;. Deciding +so, and using all that nice &Qt;-streaming and stuff, will easily lead +to the middleware becoming a &Qt;-only (or rather &kde;-only) thing. I +mean: as soon as I'll see the GNOMEs using &DCOP;, too, or something like +that, I am certainly proven wrong. +</para> + +<para> +While I do know that &DCOP; basically doesn't know about the data types +it sends, so that you could use &DCOP; without using &Qt;, look at how +it is used in daily &kde; usage: people send types like +<classname>QString</classname>, <classname>QRect</classname>, +<classname>QPixmap</classname>, <classname>QCString</classname>, ..., +around. These use &Qt;-serialization. So if somebody choose to support +&DCOP; in a GNOME program, he would either have to claim to use +<classname>QString</classname>,... types (although he doesn't do so), +and emulate the way &Qt; does the streaming, or he would send other +string, pixmap and rect types around, and thus not be interoperable. +</para> + +<para> +Well, whatever. &arts; was always intended to work with or without +&kde;, with or without &Qt;, with or without X11, and maybe even with or +without &Linux; (and I have even no problems with people who port it to +a popular non-free operating systems). +</para> + +<para> +It is my position that non-&GUI;-components should be written +non-&GUI;-dependant, to make sharing those among wider amounts of +developers (and users) possible. +</para> + +<para> +I see that using two <acronym>IPC</acronym> protocols may cause +inconveniences. Even more, if they are both non-standard. However, for +the reasons given above, switching to &DCOP; is no option. If there is +significant interest to find a way to unite the two, okay, we can +try. We could even try to make &MCOP; speak <acronym>IIOP</acronym>, +then we'd have a <acronym>CORBA</acronym> <acronym>ORB</acronym> ;). +</para> + +<para> +I talked with Matthias Ettrich a bit about the future of the two +protocols, and we found lots of ways how things could go on. For +instance, &MCOP; could handle the message communication in &DCOP;, thus +bringing the protocols a bit closer together. +</para> + +<para> +So some possible solutions would be: +</para> + +<itemizedlist> +<listitem> +<para> +Write an &MCOP; - &DCOP; gateway (which should be possible, and would +make interoperation possible) - note: there is an experimental +prototype, if you like to work on that. +</para> +</listitem> + +<listitem> +<para> +Integrate everything &DCOP; users expect into &MCOP;, and try to only do +&MCOP; - one could add an <quote>man-in-the-middle-option</quote> to +&MCOP;, too ;) +</para> +</listitem> + +<listitem> +<para> +Base &DCOP; on &MCOP; instead of libICE, and slowly start integrating +things closer together. +</para> +</listitem> +</itemizedlist> + +<para> +However, it may not be the worst possibility to use each protocol for +everything it was intended for (there are some big differences in the +design goals), and don't try to merge them into one. +</para> + +</sect1> +</chapter> diff --git a/doc/artsbuilder/midi.docbook b/doc/artsbuilder/midi.docbook new file mode 100644 index 00000000..611b457c --- /dev/null +++ b/doc/artsbuilder/midi.docbook @@ -0,0 +1,474 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="midi"> +<title>&MIDI;</title> + +<sect1 id="midi-overview"> +<title>Overview</title> + +<!-- what-to-say-here: aRts has three roles + * moving midi events around between applications + * abstracting the hardware + * synthesizer --> + +<para> +The &MIDI; support in &arts; can do a number of things. First of all, it +allows <emphasis>communication</emphasis> between different pieces of +software that produce or consume &MIDI; events. If you for instance have +a sequencer and a sampler that are both &arts; aware, &arts; can send +the &MIDI; events from the sequencer to the sampler. +</para> + +<para> +On the other hand, &arts; can also help applications to +<emphasis>interact with the hardware</emphasis>. If a piece of software +(for instance the sampler) works together with &arts;, it will be able +to receive the &MIDI; events from an external &MIDI; keyboard as well. +</para> + +<para> +Finally, &arts; makes a great <emphasis>modular +synthesizer</emphasis>. It is designed to do exactly this. So you can +build instruments out of small modules using artsbuilder, and then use +these instruments to compose or play music. Synthesis does not +necessarily mean pure synthesis, there are modules you can use to play +samples. So &arts; can be a sampler, synthesizer, and so on, and being +fully modular, it is very easy to extend, very easy to experiment with, +powerful and flexible. +</para> +</sect1> + +<sect1 id="midi-manager"> +<title>The &MIDI; Manager</title> +<!-- what-to-say-here: + * how to use artscontrol - view midimanager + * what does autorestore do? (not yet implemented - so not yet documented) --> + +<para> +The central component in &arts; that keeps track which applications are +connected and how midi events should be passed between them is the midi +manager. To see or influence what it does, start artscontrol. Then, +choose <menuchoice><guilabel>View</guilabel><guilabel>View Midi +Manager</guilabel> </menuchoice> from the menu. +</para> + +<para> +On the left side, you will see <guilabel>Midi Inputs</guilabel>. There, +all objects that produce &MIDI; events, such as an external &MIDI; port +which sends data from a connected &MIDI; keyboard, a sequencer which +plays a song and so on will be listed. On the right side, you will see +<guilabel>Midi Outputs</guilabel>. There, all things that consume &MIDI; +events, such as a simulated sampler (as software), or the external +&MIDI; port where your hardware sampler outside your computer is +connected will be listed. New applications, such as sequencers and so on +will register themselves, so the list will be changing over time. +</para> + +<para> +You can connect inputs and outputs if you mark the input on the left +side and the output on the right side, and choose +<guilabel>Connect</guilabel> with the button +below. <guilabel>Disconnect</guilabel> works the same. You will see what +is connected as small lines between the inputs and outputs, in the +middle of the window. Note that you can connect one sender to more than +one receiver (and the other way round). +</para> + +<para> +Programs (like the Brahms sequencer) will add themselves when they start +and be removed from the list when they are terminated. But you can also +add new things in the <guilabel>Add</guilabel> menu: +</para> + +<variablelist> +<varlistentry> +<term><guimenuitem>System Midi Port (OSS)</guimenuitem></term> +<listitem> +<para> +This will create a new &arts; object that talks to an external midi +port. +</para> + +<para> +As external midi ports can do both, send and receive data, choosing this +option will add a midi input and a midi output. Under &Linux;, you +should either have an <acronym>OSS</acronym> (or +<acronym>OSS</acronym>/Free, the thing that comes with your &Linux; +kernel) or an <acronym>ALSA</acronym> driver for your soundcard +installed, to make it work. It will ask for the name of the +device. Usually, this is <filename +class="devicefile">/dev/midi</filename> or <filename +class="devicefile">/dev/midi00</filename>. +</para> + +<para> +However, if you have more than one &MIDI; device or a &MIDI; loopback +driver installed, there might be more choices. To see information about +your midi ports, start the &kcontrolcenter;, and choose +<menuchoice><guilabel>Information</guilabel> +<guilabel>Sound</guilabel></menuchoice>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>aRts Synthesis Midi Output</guimenuitem></term> +<listitem> +<para> +This will add a new &MIDI; output with an &arts; synthesis +instrument. If you choose the menu item, a dialog will pop up, and allow +you to choose an instrument. You can create new instruments using +artsbuilder. All <literal role="extension">.arts</literal> files with a +name that starts with <filename>instrument_</filename> will appear here. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="brahms"> +<title>Using &arts; & Brahms</title> + +<para> +Actually, getting started is quite easy. You need a &kde; 2.1-aware +version of &brahms;, which can be found in the <literal>kmusic</literal> +<acronym>CVS</acronym> module. There is also information on how to get +&brahms; on the <ulink url="http://www.arts-project.org/">aRts +Homepage</ulink> in the Download section. +</para> + +<para> +When you start it, it will show up in the &MIDI; manager. If you want to +do synthesis, simply add a synthesis &MIDI; instrument via +<menuchoice><guilabel>Add</guilabel><guilabel>aRts Synthesis Midi +Output</guilabel></menuchoice>. +</para> + +<para> +Choose an instrument (for instance <guilabel>organ2</guilabel>). Connect +them using the <guilabel>Connect</guilabel> button. Finally, you can +start composing in &brahms;, and the output will be synthesized with +&arts;. +</para> + +<para> +It is usually a good idea to have the &artscontrol; window open, and see +that the volume is not too loud (quality gets bad when the bars hit the +upper limit). Now you can start working on a new &arts; demosong, and if +you are done, you can get it published on aRts-project.org ;-). +</para> + +<!-- TODO: how to do more than one instrument in Brahms (hm, not implemented + yet, not documented yet), how to use samples, mapping and so on. These + things need to be implemented, too. --> + +</sect1> + +<sect1 id="midisend"> +<title>midisend</title> + +<para> +<command>midisend</command> is a small application that will allow you +to send &MIDI; events from +the shell. It will register as client like all other applications. The most +simple way to use it is to do + +<screen><prompt>%</prompt> <userinput><command>midisend</command> <option>-f</option> <parameter><replaceable>/dev/midi00</replaceable></parameter></userinput> </screen> + +which will achieve about the same as adding a system &MIDI; port in +&artscontrol;. (Not quite, because <command>midisend</command> only sends events). The difference is that it is +easy for instance to start <command>midisend</command> on different computers (and like that, +use network transparency). +</para> + +<para> +It is also possible to make <command>midisend</command> send data from +<filename class="devicefile">stdin</filename>, which you can use to pipe +data from non-&arts;-aware applications to &arts;, like this: + +<screen><prompt>%</prompt> <userinput><command><replaceable>applicationwhichproducesmidieventsonstdout</replaceable></command> | <command>midisend</command> <option>-f</option> <option><replaceable>-</replaceable></option></userinput></screen> +<!-- TODO: document all options --> +</para> + +</sect1> + +<sect1 id="midi-creating-instruments"> +<title>Creating Instruments</title> + +<para> +The way &arts; does midi synthesis is this: you have a structures which +has some input ports, where it gets the frequency, velocity (volume) and +a parameter which indicates whether the note is still pressed. The +structure should now synthesize exactly that note with that volume, and +react on the pressed parameter (where pressed = 1 means the user still +holds down that key and pressed = 0 means the user has released that +key). +</para> + +<para> +When &MIDI; events arrive, &arts; will create new structures for the +notes as needed, give them the parameters, and clean them up once they +are done. +</para> + +<para> +To create and use such a structure, you should do the following: +</para> + +<itemizedlist> +<listitem> +<para> +To get started, the most convenient way is to open +<filename>template_Instrument.arts</filename> in &arts-builder;. +</para> + +<para> +This can be achieved by using +<menuchoice><guimenu>File</guimenu><guimenuitem>Open +Example...</guimenuitem></menuchoice> and choosing +<guimenuitem>template_Instrument</guimenuitem> in the file +selector. This will give you an empty structure with the required +parameters, which you only need to <quote>fill out</quote>. +</para> +</listitem> + +<listitem> +<para> +To process the pressed parameter, it is convenient to use +Synth_ENVELOPE_ADSR, or, in case of playing some drum wav, +just play it anyway, and ignore the pressed parameter. +</para> +</listitem> + +<listitem> +<para> +The structure should indicate when it is no longer needed on the +<quote>done</quote> output. If done is <returnvalue>1</returnvalue>, +&arts; assumes that it can delete the structure. Conveniently, the ADSR +envelope provides a parameter when it is done, so you just need to +connect this to the done output of the structure. +</para> +</listitem> + +<listitem> +<para> +You should rename your structure to some name starting with +<filename>instrument_</filename>, like +<filename>instrument_piano.arts</filename> - you should save the file +under the same name, in your <filename +class="directory">$<envar>HOME</envar>/arts/structures</filename> +folder (which is where artsbuilder wants to save files normally). +</para> +</listitem> + +<listitem> +<para> +Finally, once you saved it, you will be able to use it with &artscontrol; +in the &MIDI; manager <!-- todo link to midimanager -->.</para> +</listitem> + +<listitem> +<para> +Oh, and of course your structure should play the audio data it generates +to the left and right output of the structure, which will then be played +via audio manager (you can see that in &artscontrol;), so that you +finally can hear it (or postprocess it with effects). +</para> +</listitem> +</itemizedlist> + +<para> +A good way to learn how to do instruments is to open an existing +instrument via <menuchoice><guilabel>File</guilabel><guilabel>Open +Example</guilabel> </menuchoice> and see how it works ;) +</para> +</sect1> + +<sect1 id="mapped-instruments"> +<title>Mapped Instruments</title> + +<para> +Mapped instruments are instruments, that behave differently depending on +the pitch, the program, the channel or the velocity. You could for +instance build a piano of 5 octaves, using one sample for each octave +(pitchshifting it accordingly). That sounds a whole lot better than only +using one sample. +</para> + +<para> +You could also build a drum map, that plays one specific drum sample per +key. +</para> + +<para> +Finally, it is very useful if you put quite some different sounds into +one mapped instrument on different programs. That way, you can use your +sequencer, external keyboard or other &MIDI; source to switch between +the sounds without having to tweak &arts; as you work. +</para> + +<para> +A good example for this is the instrument <filename>arts_all</filename>, +which just puts together all instruments that come with &arts; in one +map. That way, you just need to setup once in &artscontrol; to use this +<quote>instrument</quote>, and then, you can compose a whole song in a +sequencer without ever bothering about &arts;. Need another sound? +Simply change the program in the sequencer, and &arts; will give you +another sound. +</para> + +<para> +Creating such maps is pretty straightforward. You just need to create a +textfile, and write rules which look like this: +</para> + +<programlisting> +ON <replaceable>[ conditions ...]</replaceable> DO structure=<replaceable>somestructure</replaceable>.arts +</programlisting> + +<para> +The conditions could be one or more than one of the following: +</para> + +<variablelist> + +<varlistentry> +<term><option>pitch</option></term> + +<listitem> +<para> +The pitch that is being played. You would use this if you want to split +your instrument depending on the pitch. In our initial examples, a piano +which uses different samples for different octaves would use this as +condition. You can specify a single pitch, like +<userinput><option>pitch</option>=<parameter>62</parameter></userinput> +or a range of pitches, like +<userinput><option>pitch</option>=<parameter>60</parameter>-<parameter>72</parameter></userinput>. +The possible pitches are between <parameter>0</parameter> and +<parameter>127</parameter>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>program</option></term> +<listitem> +<para> +The program that is active on the channel that the note is being sent +on. Usually, sequencers let you choose the <quote>instrument</quote> via +the program setting. Single programs or ranges are allowed, that is +<userinput><option>program</option>=<parameter>3</parameter></userinput> +or +<userinput><option>program</option>=<parameter>3</parameter>-<parameter>6</parameter></userinput>. +The possible programs are between <parameter>0</parameter> and +<parameter>127</parameter>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>channel</option></term> +<listitem> +<para> +The channel that that the note is being sent on. Single channels or +ranges are allowed, that is +<userinput><option>channel</option>=<parameter>0</parameter></userinput> +or +<userinput><option>channel</option>=<parameter>0</parameter>-<parameter>8</parameter></userinput>. +The possible channels are between <parameter>0</parameter> and +<parameter>15</parameter>. +</para> +</listitem> + +</varlistentry> +<varlistentry> +<term><option>velocity</option></term> +<listitem> +<para> +The velocity (volume) that that the note has. Single velocities (who +would use that?) or ranges are allowed, that is +<userinput><option>velocity</option>=<parameter>127</parameter></userinput> +or +<userinput><option>velocity</option>=<parameter>64</parameter>-<parameter>127</parameter></userinput>. +The possible velocities are between <parameter>0</parameter> and +<parameter>127</parameter>. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +A complete example for a map would be (this is taken from the current +<filename>instrument_arts_all.arts-map</filename>): +</para> + +<programlisting> +ON program=0 DO structure=instrument_tri.arts +ON program=1 DO structure=instrument_organ2.arts +ON program=2 DO structure=instrument_slide1.arts +ON program=3 DO structure=instrument_square.arts +ON program=4 DO structure=instrument_neworgan.arts +ON program=5 DO structure=instrument_nokind.arts +ON program=6 DO structure=instrument_full_square.arts +ON program=7 DO structure=instrument_simple_sin.arts +ON program=8 DO structure=instrument_simple_square.arts +ON program=9 DO structure=instrument_simple_tri.arts +ON program=10 DO structure=instrument_slide.arts +ON program=11 pitch=60 DO structure=instrument_deepdrum.arts +ON program=11 pitch=61 DO structure=instrument_chirpdrum.arts +</programlisting> + +<para> +As you see, the structure is chosen depending on the program. On +program 11, you see a <quote>drum map</quote> (with two entries), which +would play a <quote>deepdrum</quote> on C-5 (pitch=60), and a +<quote>chirpdrum</quote> on C#5 (pitch=61). +</para> + +<para> +To make map files automatically appear in &artscontrol; as choice for +the instrument, they have to be called +<filename>instrument_<replaceable>something</replaceable>.arts-map</filename> +and reside either in your Home Folder, under <filename +class="directory">$<envar>HOME</envar>/arts/structures</filename>, or in the +&kde; folder under <filename +class="directory">$<envar>KDEDIR</envar>/usr/local/kde/share/apps/artsbuilder/examples</filename>. Structures +that are used by the map can either be given with an absolute path, or +relative to the folder the map file resides in. +</para> + +<para> +Extending the arts_all map or even making a complete general &MIDI; map +for &arts; is a good idea for making &arts; easier to use +out-of-the-box. Please consider contributing interesting instruments +you make, so that they can be included in further version of &arts;. +</para> +</sect1> + +<!-- TODO: Maybe helpful + * using an external keyboard + * loopback midi device + +<sect1 id="quick-start"> +<title>Quick Start</title> +<para> +</para> +</sect1> +<sect1 id="internal-details"> +<title>More Internal Details</title> +<para> +</para> +</sect1> + +<sect1 id="other-considerations"> +<title>Other Considerations</title> +<para> +</para> +</sect1> +--> + +</chapter> diff --git a/doc/artsbuilder/midiintro.docbook b/doc/artsbuilder/midiintro.docbook new file mode 100644 index 00000000..18d6fc93 --- /dev/null +++ b/doc/artsbuilder/midiintro.docbook @@ -0,0 +1,14 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE appendix PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<appendix id="midi-introduction"> + +<title>Introduction to <acronym>MIDI</acronym></title> + +<para> +Not yet written +</para> + +</appendix> diff --git a/doc/artsbuilder/modules.docbook b/doc/artsbuilder/modules.docbook new file mode 100644 index 00000000..d0da50d8 --- /dev/null +++ b/doc/artsbuilder/modules.docbook @@ -0,0 +1,1336 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-modules"> +<title>&arts; modules</title> + + <sect1 id="modules-introduction"> +<title>Introduction</title> + +<para> +This chapter describes all of the standard &arts; modules. One of the +most powerful features of &arts;, modules can be connected together into +structures to implement new functions such as effects and instruments. +</para> + +<para> +Modules are broken down into two categories. Synthesis modules are used +for implementing the <quote>plumbing</quote> that manipulates multimedia +data streams to implement new effects, instruments, mixers, and +applications. Visual modules allow you to provide a graphical user +interface to control the sound structures that are built up with the +synthesis modules. +</para> + +</sect1> + +<sect1 id="synth-modules-reference"> +<title>Synthesis Modules Reference</title> +<para> +</para> + +<sect2 id="mcat-synth-arithmetic-mixing"> +<title>Arithmetic + Mixing</title> + +<para> +</para> + +<sect3 id="mref-synth-add-sect"> +<title>Synth_ADD</title> +<anchor id="mref-synth-add" /> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_ADD.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_ADD</phrase></textobject> +</mediaobject> + +<para> +This adds two signals. +</para> + +</sect3> + +<sect3 id="mref-synth-mul-sect"> +<title>Synth_MUL</title> +<anchor id="mref-synth-mul"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_MUL.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_MUL</phrase></textobject> +</mediaobject> + +<para> +This multiplies a signal by a factor. You can use this to scale signals +down (0 < factor < 1) or up (factor > 1) or invert signals +(factor < 0). Note that the factor may be a signal and don't has to +be constant (⪚ envelope or real signal). +</para> + +</sect3> + +<sect3 id="mref-synth-div-sect"> +<title>Synth_DIV</title> +<anchor id="mref-synth-div"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_DIV.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_DIV</phrase></textobject> +</mediaobject> + +<para> +This divides a signal by a factor. You can use this to do divide one signal +by another one. Or set invalue1 to 1 and you will get the +reciprocal of the invalue2 as outvalue. Take care that invalue2 never +reaches 0 or you will get problems with divisions by zero. +</para> + +</sect3> + +<sect3 id="mref-synth-multi-add-sect"> +<title>Synth_MULTI_ADD</title> +<anchor id="mref-synth-multi-add" /> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_MULTI_ADD.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_MULTI_ADD</phrase></textobject> +</mediaobject> + +<para> +This adds an arbitrary number of signals. If you need to sum up the +waveforms produces by four different oscillators, you for instance can +connect all their outputs to one Synth_MULTI_ADD +module. This is more efficient than using three Synth_ADD +modules. +</para> + +</sect3> + +<sect3 id="mref-synth-xfade-sect"> +<title>Synth_XFADE</title> +<anchor id="mref-synth-xfade" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_XFADE.png" format="PNG"/> +</imageobject> +<textobject><phrase>Synth_XFADE</phrase></textobject> +</mediaobject> + +<para> +This crossfades two signals. If the percentage input is -1, only the +left signal is heard, if it is 1, only the right signal is heard. When +it is 0, both signals a heard with the same volume. +</para> + +<para> +This allows you to ensure that your signal stays in a well defined +range. If you had two signals that were between -1 and 1 before +crossfading, they will be in the same range after crossfading. +</para> +</sect3> + +<sect3 id="mref-synth-autopanner-sect"> +<title>Synth_AUTOPANNER</title> +<anchor id="mref-synth-autopanner" /> + +<para> +The opposite of a crossfader. This takes a mono signal and splits it +into a stereo signal: It is used to automatically pan the input signal +between the left and the right output. This makes mixes more lively. A +standard application would be a guitar or lead sound. +</para> + +<para> +Connect a <acronym>LFO</acronym>, a sine or saw wave for example to +inlfo. and select a frequency between 0.1 and 5Hz for a traditional +effect or even more for Special <acronym>FX</acronym>. +</para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-busses"> +<title>Busses</title> + +<sect3 id="mref-synth-bus-uplink-sect"> +<title>Synth_BUS_UPLINK</title> +<anchor id="mref-synth-bus-uplink" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_BUS_UPLINK.png" + format="PNG"/> +</imageobject> +<textobject><phrase>Synth_BUS_UPLINK</phrase></textobject> +</mediaobject> + +<para> +An uplink to a bus. Give signals to left and right, and the name of the +bus where the data should go on the <quote>bus</quote> port. The +combined signal from all uplinks with this name will appear on every +downlink on that <quote>bus</quote>. +</para> +</sect3> + +<sect3 id="mref-synth-bus-downlink-sect"> +<title>Synth_BUS_DOWNLINK</title> +<anchor id="mref-synth-bus-downlink" /> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_BUS_DOWNLINK.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_BUS_DOWNLINK</phrase></textobject> +</mediaobject> + +<para> +Gets (the sum of) all data that is put to a certain bus (with the name +you specify at the <quote>bus</quote> port). +</para> +</sect3> + +</sect2> + +<!-- TODO AFTER KDE2.1: move freeverb into delays, and rename category to + Delays & reverbs --> + +<sect2 id="mcat-synth-delays"> +<title>Delays</title> + +<para> +</para> + +<sect3 id="mref-synth-delay-sect"> +<title>Synth_DELAY</title> +<anchor id="mref-synth-delay" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_DELAY.png" + format="PNG"/></imageobject></mediaobject> + +<para> +This delays the input signal for an amount of time. The time +specification must be between 0 and maxdelay for a delay between 0 and +maxdelay seconds. +</para> + +<para> +This kind of delay <emphasis>may not be used</emphasis> in feedback +structures. This is because it's a variable delay. You can modify it's +length while it is running, and even set it down to zero. But since in a +feedback structure the own output is needed to calculate the next +samples, a delay whose value could drop to zero during synthesis could +lead to a stall situation. +</para> + +<para> +Use CDELAYs in that setup, perhaps combine a small constant delay (of +0.001 seconds) with a flexible delay. +</para> + +<para> +You can also combine a CDELAY and a DELAY to achieve a variable length +delay with a minimum value in a feedback loop. Just make sure that you +have a CDELAY involved. +</para> + +</sect3> + +<sect3 id="mref-synth-cdelay-sect"> +<title>Synth_CDELAY</title> +<anchor id="mref-synth-cdelay" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_CDELAY.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_CDELAY</phrase></textobject> +</mediaobject> + +<para> +This delays the input signal for an amount of time. The time +specification must be greater than 0 for a delay of 0 seconds or more. +The delay is constant during the calculation, that means it +can't be modified. +</para> + +<para> +This saves computing time as no interpolation is done, and is useful for +recursive structures. See description above (Synth_DELAY). +</para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-envelopes"> +<title>Envelopes</title> + +<para> +</para> + +<sect3 id="mref-synth-envelope-adsr-sect"> +<title>Synth_ENVELOPE_ADSR</title> +<anchor id="mref-synth-envelope-adsr" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_ENVELOPE_ADSR.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_ENVELOPE_ADSR</phrase></textobject> +</mediaobject> + +<para> +This is a classic <acronym>ADSR</acronym> envelope which means you +specify: +</para> + +<variablelist> +<varlistentry> +<term>active</term> +<listitem> +<para> +Whether the note is being pressed right now by the user. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>invalue</term> +<listitem> +<para> +The input signal. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>attack</term> +<listitem> +<para> +The time that should pass between the user presses the note and the signal +reaching it's maximum amplitude (in seconds). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>decay</term> +<listitem> +<para> +The time that should pass between the the signal reaching it's maximum +amplitude and the signal going back to some constant level (in seconds). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>sustain</term> +<listitem> +<para> +The constant level the signal is held at afterwards, until the user +releases the note. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>release</term> +<listitem> +<para> +The time that should pass after the user has released the note until the +signal is scaled down to zero (in seconds). +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +You'll get the scaled signal at outvalue. If the <acronym>ASDR</acronym> +envelope is finished, it will set done to 1. You can use this to provide +the <quote>done</quote> output of an instrument (which will make the +instrument structure be deleted by the &MIDI; router object once the +release phase is over). +</para> + +</sect3> + +<sect3 id="mref-synth-pscale-sect"> +<title>Synth_PSCALE</title> +<anchor id="mref-synth-pscale" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_PSCALE.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_PSCALE</phrase></textobject> +</mediaobject> + +<para> +The Synth_PSCALE module will scale the audio stream that is +directed through it from a volume 0 (silent) to 1 (original loudness) +back to 0 (silent). According to the position (get the position from +Synth_SEQUENCE). The position where the peak should occur can be +given as pos. +</para> + +<para> +Example: Setting top to 0.1 means that after 10% of the note has +been played, the volume has reached its maximum, and starts decaying +afterwards. +</para> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-effects"> +<title>Effects</title> + +<sect3 id="mref-synth-freeverb-sect"> +<title>Synth_FREEVERB</title> +<anchor id="mref-synth-freeverb" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_FREEVERB.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_FREEVERB</phrase></textobject> +</mediaobject> + +<para> +This is a reverb effect. In the current implementation, it is thought to +pass a stereo signal through the reverb, and it will -add- it's reverb +effect to the signal. +</para> + +<note> +<para> +This means that it can be used inside an StereoEffectStack as well. +</para> +</note> + +<para> +The input signal should be connected to (inleft, inright), the output +signal will be (outleft, outright). +</para> + +<para> +The parameters which you can configure are: +</para> + +<variablelist> +<varlistentry> +<term>roomsize</term> +<listitem> +<para> +The size of the room which the reverb simulates (range: 0..1, where 1 is +the largest possible room). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>damp</term> +<listitem> +<para> +This specifies a filter which will make the simulated room absorb high +frequencies (range 0..1, where 1 means absorb high frequencies quite +aggressive). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>wet</term> +<listitem> +<para> +The amount of reverb-signal (that is, the amount of the signal that +should be modified by the filters, resulting in a <quote>wet</quote>, +that is <quote>reverb sound</quote>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>dry</term> +<listitem> +<para> +The amount of pure signal passed through, resulting in an echo (or +combined delay) rather than reverb effect (range: 0..1). +</para> +<!-- TODO: do some measurements to show that this documentation -is- correct, +I am not sure if it is echo, or really pure (non-delayed), or multiple delay +or whatever --> +</listitem> +</varlistentry> + +<varlistentry> +<term>width</term> +<listitem> +<para> +The amount of stereo-magic the reverb algorithm adds to the reverb +effect, making the reverb sound wider in the stereo panorama (range: +0..1). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>mode</term> +<listitem> +<para> +[ TODO: I think if mode is 1, the reverb holds the current image of the +sound, whereas 0 is normal operation ] +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3 id="mref-synth-tremolo-sect"> +<title>Synth_TREMOLO</title> +<anchor id="mref-synth-tremolo" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_TREMOLO.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_TREMOLO</phrase></textobject> +</mediaobject> + +<para> +The tremolo module modulates the amplitude according to a +<acronym>LFO</acronym>-Wave. Traditionally you would use a sine wave +but why limit yourself? What you get is a very intense effect that cuts +through most arrangements because of its high dynamic range. The +tremolo effect is still one of guitarists favorite effects although +it's not as popular as in the 1960's. +</para> + +<para> +[ TODO: currently this is implemented as invalue + abs(inlfo) - maybe it +would make more sense to implement it as invalue * (1+inlfo*depth), +where depth would be a parameter between 0..1 - decide this after &kde;2.1 +; if you have a comment, send a mail to the &arts; list ;). ] +</para> + +</sect3> +<sect3 id="mref-synth-fx-cflanger-sect"> +<title>Synth_FX_CFLANGER</title> +<anchor id="mref-synth-fx-cflanger" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_FX_CFLANGER.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_FX_CFLANGER</phrase></textobject> +</mediaobject> + +<para> +A flanger is a time-varying delay effect. To make development of complex +flanger effects simpler, this module is provided, which contains the +core of a one-channel flanger. +</para> + +<para>It has the following ports:</para> + +<variablelist> +<varlistentry> +<term>invalue</term> +<listitem> +<para> +The signal which you want to process. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>lfo</term> +<listitem> +<para> +Preferably a sine wave which modulates the delay time inside the +flanger (-1 .. 1). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>mintime</term> +<listitem> +<para> +The minimum value for the delay inside the flanger in milliseconds. +Suggested values: try something like 1 ms. Please use values < 1000 +ms. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>maxtime</term> +<listitem> +<para> +The minimum value for the delay inside the flanger in milliseconds. +Suggested values: try something like 5 ms. Please use values < 1000 +ms. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>outvalue</term> +<listitem> +<para> +The output signal. It is important that you mix that with the +original (unflanged) signal to get the desired effect. +</para> +</listitem> +</varlistentry> +</variablelist> + +<tip> +<para> +You can use this as a basis for a chorus effect. +</para> +</tip> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-filters"> +<title>Filters</title> + +<sect3 id="mref-synth-pitch-shift-sect"> +<title>Synth_PITCH_SHIFT</title> +<anchor id="mref-synth-pitch-shift" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_PITCH_SHIFT.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_PITCH_SHIFT</phrase></textobject> +</mediaobject> + +<para> +This pitch shifting effect changes the frequency of the input signal +without affecting the speed. An application for this is for instance +changing the pitch of your voice while you record (and replay) it in +realtime. +</para> + +<para> +The <emphasis>speed</emphasis> parameter is the relative speed with +which the signal will be replayed. So a speed of two would make it sound +twice as high (&ie; an input frequency of 440 Hz would result in an +output frequency of 880 Hz). +</para> + +<para> +The <emphasis>frequency</emphasis> parameter is used internally to +switch between different grains of the signal. It is tunable, and +depending on your choice, the pitch shifting will sound more or less +realistic for your use case. A good value to start with is something +like 5 or 10. +</para> + +</sect3> + +<sect3 id="mref-synth-shelve-cutoff-sect"> +<title>Synth_SHELVE_CUTOFF</title> +<anchor id="mref-synth-shelve-cutoff" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_SHELVE_CUTOFF.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_SHELVE_CUTOFF</phrase></textobject> +</mediaobject> + +<para> +Filters out all frequencies over the cutoff frequency. +</para> + +</sect3> + +<sect3 id="mref-synth-brickwall-limiter-sect"> +<title>Synth_BRICKWALL_LIMITER</title> +<anchor id="mref-synth-brickwall-limiter" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_BRICKWALL_LIMITER.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_BRICKWALL_LIMITER</phrase></textobject> +</mediaobject> + +<para> +This modules clips a signal to make it fit into the range of [-1;1]. It +doesn't do anything to prevent the distortion that happens when clipping +loud signals. You can use this as effect (for instance to create a +slightly clipped sine wave). However, it's probably a good idea to run +the signal through a lowpass filter afterwards if you do so, to make it +sound less aggressive. +</para> +</sect3> + +<sect3 id="mref-synth-std-equalizer-sect"> +<title>Synth_STD_EQUALIZER</title> +<anchor id="mref-synth-std-equalizer" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_STD_EQUALIZER.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_STD_EQUALIZER</phrase></textobject> +</mediaobject> + +<para> +This is a nice parametric equalizer building block. It's parameters are: +</para> + +<variablelist> +<varlistentry> +<term>invalue, outvalue</term> +<listitem> +<para> +The signal that gets filtered by the equalizer. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>low</term> +<listitem> +<para> +How low frequencies should be changed. The value is in dB, while 0 means +don't change low frequencies, -6 would mean take them out by 6dB, and +6 +mean boost them by 6dB. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>mid</term> +<listitem> +<para> +How middle frequencies should be changed by the equalizer in dB (see +low). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>high</term> +<listitem> +<para> +How high frequencies should be changed by the equalizer in dB (see low). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>frequency</term> +<listitem> +<para> +This is the center frequency of the equalizer in Hz, the mid frequencies +are around that spectrum, the low and high frequencies below and above. +Note that the frequency may not be higher than half the sampling rate, +usually that is 22050 Hz, and not lower than 1 Hz. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>q</term> +<listitem> +<para> +This influences how broad the mid spectrum is. It must be be a positive +number > 0. A value of one is reasonable, higher values of q mean a +narrower spectrum of middle frequencies. Lower values than one mean a +broader spectrum. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3 id="mref-synth-rc-sect"> +<title>Synth_RC</title> +<anchor id="mref-synth-rc" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_RC.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_RC</phrase></textobject> +</mediaobject> + +<para> +A damped resonator filter filtering all frequencies around some peak +value. There is no useful way of specifying middle frequency (that +won't be cut), since the input are two strange constants f and b. The +code is very old, from the first days of the synthesizer, and will +probably replaced by a new filter which will have a frequency and a +resonance value as parameters. +</para> + +<para> +Try something like b=5, f=5 or b=10, f=10 or b=15, f=15 though. +</para> + +</sect3> + +<sect3 id="mref-synth-moog-vcf-sect"> +<title>Synth_MOOG_VCF</title> +<anchor id="mref-synth-moog-vcf" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_MOOG_VCF.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_MOOG_VCF</phrase></textobject> +</mediaobject> + +<para> +Filters out all frequencies over the cutoff frequency (it's a 24db 4pole +filter, which filters -24db per octave above the cutoff frequency), but +offers an additional parameter for tuning the filter resonance, while 0 +means no resonance and 4 means self oscillation. +</para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-midi-sequencing"> +<title>Midi + Sequencing</title> + +<sect3 id="mref-synth-midi-test-sect"> +<title>Synth_MIDI_TEST</title> +<anchor id="mref-synth-midi-test" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_TEST.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_MIDI_TEST</phrase></textobject> +</mediaobject> + +<para> +This modules loads an instrument structure from a file, and registers +itself as midi output with the &arts; &MIDI; manager. Notes sent to this +output will result in instrument voices being created. +</para> + +<note> +<para> +You can setup something like this more convenient in &artscontrol; than +manually in &arts-builder;. +</para> +</note> + +</sect3> + +<sect3 id="mref-synth-sequence-sect"> +<title>Synth_SEQUENCE</title> +<anchor id="mref-synth-sequence" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_SEQUENCE.png" +format="PNG" /></imageobject></mediaobject> + +<para> +Will play a sequence of notes over and over again. The notes are given +in tracker notation, and are separated by semicolons. An example is +<literal>A-3;C-4;E-4;C-4;</literal>. The speed is given as seconds per +note, so if you want to get 120 bpm, you will probably specify 0.5 +seconds/note, as 60 seconds/0.5 seconds per note=120 bpm. +</para> + +<para> +You can give each note an length relative to the speed by using a colon +after the note and then then +length. <literal>A-3:2;C-4:0.5;D-4:0.5;E-4;</literal> demonstrates +this. As you see, midi composing programs tend to offer more comfort ;) +</para> + +<para> +The Synth_SEQUENCE gives additional information about the +position of the note it is playing right now, while 0 means just started +and 1 means finished. This information you can use with +Synth_PSCALE (see below). +</para> +</sect3> + +<sect3 id="mref-synth-sequence-freq-sect"> +<title>Synth_SEQUENCE_FREQ</title> +<anchor id="mref-synth-sequence-freq" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_SEQUENCE_FREQ.png" +format="PNG" /></imageobject></mediaobject> + +<para> +This module works just like Synth_SEQUENCE with the only difference that +you don't write notenames but frequencies. +</para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-samples"> +<title>Samples</title> + +<sect3 id="mref-synth-play-wav-sect"> +<title>Synth_PLAY_WAV</title> +<anchor id="mref-synth-play-wav" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_PLAY_WAV.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_PLAY_WAV</phrase></textobject> +</mediaobject> + +<para> +This will play a <literal role="extension">wav</literal> file. It will +only be present if you have libaudiofile on your computer. The wave file +will start as soon as the module gets created. +</para> + +<para> +It will stop as soon as it's over, then finished will be set to 1. The +speed parameter can be used to replay the file faster or slower, where +1.0 is the normal (recorded) speed. +</para> +<!-- TODO: KDE2.2: check that this really works together in instruments with +the done parameter things ;) --> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-soundio"> +<title>Sound IO</title> + +<sect3 id="mref-synth-play-sect"> +<title>Synth_PLAY</title> +<anchor id="mref-synth-play" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_PLAY.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_PLAY</phrase></textobject> +</mediaobject> + +<important> +<para> +You will normally not need this module, unless you are writing +standalone applications. Inside &artsd;, there normally is already a +Synth_PLAY module, and creating another one will not work. +</para> +</important> + +<para> +The Synth_PLAY-module will output your audio signal to the +soundcard. The left and right channels should contain the +<emphasis>normalized</emphasis> input for the channels. If your input +is not between -1 and 1, you get clipping. +</para> + +<para> +As already mentioned, there may only be one Synth_PLAY module +used, as this one directly accesses your soundcard. Use busses if you +want to mix more than one audio stream together before playing. Use the +Synth_AMAN_PLAY module to get something like an output +inside &artsd;. +</para> + +<para> +Note that Synth_PLAY also does the timing of the whole +structure. This means: no Synth_PLAY = no source for timing = no +sound. So you absolutely need (exactly) one Synth_PLAY object. +</para> + +</sect3> + +<sect3 id="mref-synth-record-sect"> +<title>Synth_RECORD</title> +<anchor id="mref-synth-record" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_RECORD.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_RECORD</phrase></textobject> +</mediaobject> + +<important> +<para>You will normally not need this module, unless you are writing +standalone applications. Inside artsd, there normally is already a +Synth_RECORD module, and creating another one will not work. +</para> +</important> + +<para> +The Synth_RECORD-module will record a signal from the soundcard. +The left and right channels will contain the input for the channels +(between -1 and 1). +</para> + +<para> +As already mentioned, there may only be one Synth_RECORD module +used, as this one directly accesses your soundcard. Use busses if you +want to use the recorded audio stream in more than one place. Use the +Synth_AMAN_RECORD module to get something like an input +inside artsd. For this to work, &artsd; must run <emphasis>with full +duplex enabled </emphasis>. +</para> +</sect3> + +<sect3 id="mref-synth-aman-play-sect"> +<title>Synth_AMAN_PLAY</title> +<anchor id="mref-synth-aman-play" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_AMAN_PLAY.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_AMAN_PLAY</phrase></textobject> +</mediaobject> + +<para> +The Synth_AMAN_PLAY-module will output your audio signal. +It is nice (but not necessary) if you output a normalized signal +(between -1 and 1). +</para> + +<para> +This module will use the audio manager to assign where the signal will +be played. The audio manager can be controlled through &artscontrol;. To +make it more intuitive to use, it is good to give the signal you play a +name. This can be achieved through setting +<emphasis>title</emphasis>. Another feature of the audio manager is to +be able to remember where you played a signal the last time. To do so it +needs to be able to distinguish signals. That is why you should assign +something unique to <emphasis>autoRestoreID</emphasis>, too. +</para> +</sect3> + +<sect3 id="mref-synth-aman-record-sect"> +<title>Synth_AMAN_RECORD</title> +<anchor id="mref-synth-aman-record" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_AMAN_RECORD.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_AMAN_RECORD</phrase></textobject> +</mediaobject> + +<para> +The Synth_AMAN_RECORD-module will record an audio signal +from an external source (&ie;. line in/microphone) within &artsd;. The +output will be a normalized signal (between -1 and 1). +</para> + +<para> +This module will use the audio manager to assign where the signal will +be played. The audio manager can be controlled through artscontrol. To +make it more intuitive to use, it is good to give the signal you record +a name. This can be achieved through setting +<emphasis>title</emphasis>. Another feature of the audio manager is to +be able to remember where you recorded a signal the last time. To do so +it needs to be able to distinguish signals. That is why you should +assign something unique to <emphasis>autoRestoreID</emphasis>, too. +</para> +</sect3> + +<sect3 id="mref-synth-capture-sect"> +<title>Synth_CAPTURE</title> +<anchor id="mref-synth-capture" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_CAPTURE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_CAPTURE</phrase></textobject> +</mediaobject> + +<para> +The Synth_CAPTURE-module will write an audio signal to a wave +file on your hard disc. The file will always be called +<filename>/tmp/mcop-<replaceable>usename</replaceable>/capture.wav</filename> +</para> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-tests"> +<title>Tests</title> + +<sect3 id="mref-synth-nil-sect"> +<title>Synth_NIL</title> +<anchor id="mref-synth-nil" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_NIL.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_NIL</phrase></textobject> +</mediaobject> + +<para> +This just does nothing. It is only useful for test situations. +</para> + +</sect3> + +<sect3 id="mref-synth-debug-sect"> +<title>Synth_DEBUG</title> +<anchor id="mref-synth-debug" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_DEBUG.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_DEBUG</phrase></textobject> +</mediaobject> + +<para> +You can use this for debugging. It will print out the value of the +signal at invalue in regular intervals (ca. 1 second), combined with the +comment you have specified. That way you can find out if some signals +stay in certain ranges, or if they are there at all. +</para> +</sect3> + +<sect3 id="mref-synth-midi-debug-sect"> +<title>Synth_MIDI_DEBUG</title> +<anchor id="mref-synth-midi-debug" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_DEBUG.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_MIDI_DEBUG</phrase></textobject> +</mediaobject> + +<para> +You can use this to debug how your &MIDI; events are actually arriving +in &arts;. +</para> + +<para> +When a MIDI_DEBUG is running &artsserver; will print out a lines +like: +</para> + +<screen><computeroutput>201 100753.837585 on 0 42 127</computeroutput></screen> + +<screen><computeroutput>202 101323.128355 off 0 42</computeroutput></screen> + +<para> +While the first line would be telling you that 100753ms (that is 100 +seconds) after the MIDI_DEBUG started, a &MIDI; on event arrived +on channel 0. This midi on event had the velocity (volume) of 127, the +loudest possible. The next line shows the midi release event. [ TODO: +this does not work currently, make it work, and do it via &MIDI; manager +]. +</para> +</sect3> + +<sect3 id="mref-synth-data-sect"> +<title>Synth_DATA</title> +<anchor id="mref-synth-data" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_DATA.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_DATA</phrase></textobject> +</mediaobject> + +<para> +This creates a signal with a constant number. +</para> +<!-- TODO: this doesn't really belong in test, does it? --> +</sect3> +</sect2> + +<sect2 id="mcat-synth-osc-mod"> +<title>Oscillation & Modulation</title> + +<sect3 id="mref-synth-frequency-sect"> +<title>Synth_FREQUENCY</title> +<anchor id="mref-synth-frequency" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_FREQUENCY.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_FREQUENCY</phrase></textobject> +</mediaobject> + +<para> +All oscillators in &arts; don't require a frequency as input, but a +position in the wave. The position should be between 0 and 1, which maps +for a standard Synth_WAVE_SIN object to the range +0..2*pi. To generate oscillating values from a frequency, a +Synth_FREQUENCY modules is used. +</para> +</sect3> + +<sect3 id="mref-synth-fm-source-sect"> +<title>Synth_FM_SOURCE</title> +<anchor id="mref-synth-fm-source" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_FM_SOURCE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_FM_SOURCE</phrase></textobject> +</mediaobject> + +<para> +This is used for frequency modulation. Put your frequency to the +frequency input and put another signal on the modulator input. Then set +modlevel to something, say 0.3. The frequency will be modulated with +modulator then. Just try it. Works nice when you put a feedback in +there, that means take a combination of the delayed output signal from +the Synth_FM_SOURCE (you need to put it to some oscillator +as it only takes the role of Synth_FREQUENCY) and some other +signal to get good results. +</para> + +<para> +Works nicely in combination with Synth_WAVE_SIN +oscillators. +</para> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-waveforms"> +<title>Wave Forms</title> + +<sect3 id="mref-synth-wave-sin-sect"> +<title>Synth_WAVE_SIN</title> +<anchor id="mref-synth-wave-sin" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_SIN.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_SIN</phrase></textobject> +</mediaobject> + +<para> +Sinus oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_SOURCE at the input. And get a sinus wave as +output. The pos signal specifies the position in the wave, the range +0..1 is mapped to 0..2*pi internally. +</para> + +</sect3> + +<sect3 id="mref-synth-wave-tri-sect"> +<title>Synth_WAVE_TRI</title> +<anchor id="mref-synth-wave-tri" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_TRI.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_TRI</phrase></textobject> +</mediaobject> + +<para> +Triangle oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_SOURCE at the input. And get a triangle wave as +output. The pos signal specifies the position in the wave, the range +0..1 is mapped to 0..2*pi internally. Be careful. The input signal +<emphasis>must</emphasis> be in the range 0..1 for the output signal to +produce good results. +</para> +</sect3> + +<sect3 id="mref-synth-noise-sect"> +<title>Synth_NOISE</title> +<anchor id="mref-synth-noise" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_NOISE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_NOISE</phrase></textobject> +</mediaobject> + +<para> +Noise generator. This generates a random signal between -1 and 1. +</para> + +</sect3> + +<sect3 id="mref-synth-wave-square-sect"> +<title>Synth_WAVE_SQUARE</title> +<anchor id="mref-synth-wave-square" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_WAVE_SQUARE.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_SQUARE</phrase></textobject> +</mediaobject> + +<para> +Square oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_SOURCE at the input. And get a square wave as +output. The pos signal specifies the position in the wave, the range +0..1 is mapped to 0..2*pi internally. Be careful. The input signal +<emphasis>must</emphasis> be in the range 0..1 for the output signal to +produce good results. +</para> +</sect3> + +<sect3 id="mref-synth-wave-softsaw-sect"> +<title>Synth_WAVE_SOFTSAW</title> +<anchor id="mref-synth-wave-softsaw" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_WAVE_SOFTSAW.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_SOFTSAW</phrase></textobject> +</mediaobject> + +<para> +Softened saw wave, similar in look like the Synth_WAVE_TRI +oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_SOURCE at the input. You'll get a softened saw +wave as output. The pos signal specifies the position in the wave, the +range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal +<emphasis>must</emphasis> be in the range 0..1 for the output signal to +produce good results. +</para> +</sect3> + +<sect3 id="mref-synth-wave-pulse-sect"> +<title>Synth_WAVE_PULSE</title> +<anchor id="mref-synth-wave-pulse" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_PULSE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_PULSE</phrase></textobject> +</mediaobject> + +<para> +Pulse oscillator - this module is similar in spirit like the rectangular +oscillator (Synth_WAVE_RECT), but it provides a configurable up/down +ratio, through the <emphasis>dutycycle</emphasis> parameter. Put a pos +signal from Synth_FREQUENCY or Synth_FM_SOURCE at +the input. Get a pulse wave as output. The pos signal specifies the +position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be +careful. The input signal <emphasis>must</emphasis> be in the range 0..1 +for the output signal to produce good results. +</para> +</sect3> +</sect2> +<sect2 id="mcat-synth-misc"> +<title>Miscellaneous</title> + +<sect3 id="mref-synth-compressor-sect"> +<title>Synth_COMPRESSOR</title> +<anchor id="mref-synth-compressor" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_COMPRESSOR.png" + format="PNG"/></imageobject></mediaobject> + +<para> +This module reduces the dynamic range of the signal. For example +compressors are useful in compensating for the wide variations in +loudness of somebody talking into a microphone. +</para> + +<para> +As soon as the input level exceeds a certain level (the threshold) +the signal gets compressed. It simply multiplies everything above +the threshold with the ratio, which should be a number between 0 and +1. Finally the whole signal is multiplied by the output factor. +</para> + +<para> +The attack and release arguments delay the start and end of the +compression. Use this if you, for example, still want to hear the +loud beginning of a basedrum. The argument is in milliseconds and an +attack or release of 0ms is possible but may result in a slight noise. +</para> + +</sect3> +</sect2> +</sect1> + +<sect1 id="visual-modules-reference"> +<title>Visual Modules Reference</title> + +<para> +TODO when visual modules are more "finished". +</para> +</sect1> + +</chapter> diff --git a/doc/artsbuilder/porting.docbook b/doc/artsbuilder/porting.docbook new file mode 100644 index 00000000..f039904e --- /dev/null +++ b/doc/artsbuilder/porting.docbook @@ -0,0 +1,64 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="porting"> +<title>Porting Applications to &arts;</title> + +<sect1 id="using-artsdsp"> +<title>Using &artsdsp;</title> + +<para> +The &artsdsp; utility, <link linkend="artsdsp">described +previously</link>, allows most legacy sound applications that talk to +the audio devices directly, to work properly under &arts;. Applications +written to use the Enlightenment Sound Daemon +(<application>esd</application>) will also work in most cases by running +<application>esd</application> under &artsdsp;. +</para> + +<para> +This makes a good short term solution to porting existing applications +to &kde;. However, it does not allow the application to directly take +advantage of all of the power of &arts;, such as using modules and +multimedia streams other than digital audio. If the application goes +beyond simple playing of sound files, it usually makes sense to add +native support for &arts; to the application. +</para> + +<para> +Using &arts; also means that application does not have to do as much +work -- it can leverage the functions in &arts; to handle issues like +codecs for different media formats and control of the sound hardware. +</para> + +</sect1> + +<sect1 id="adding-native-arts-support"> +<title>Adding Native &arts; support</title> + +<para> +When using &arts;, you have a number of different <link +linkend="arts-apis"><acronym>API</acronym>s</link> to choose from. The +decision of which to use depends on a number of factors, including what +type of streaming media is used (sound, &MIDI;, &CD; audio, &etc;), the +<acronym>API</acronym> features required, and whether it is written in +C++. In most cases the choice should be relatively obvious based on the +required features. +</para> + +<para> +For cross-platform portability, applications that need to run on +environments other than &kde; cannot rely on &arts; being present. Using +the plug-ins paradigm is a good way to support different multimedia +environments. Making the plug-in <acronym>API</acronym> open and +documented (especially for closed source applications) also has the +advantage of allowing someone other than the application developer to +implement an &arts; plug-in. +</para> + +</sect1> + +</chapter> + diff --git a/doc/artsbuilder/references.docbook b/doc/artsbuilder/references.docbook new file mode 100644 index 00000000..4978f723 --- /dev/null +++ b/doc/artsbuilder/references.docbook @@ -0,0 +1,56 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="references"> +<title>References</title> + +<variablelist> + +<varlistentry> +<term><ulink +url="http://multimedia.kde.org">http://multimedia.kde.org</ulink></term> +<listitem> +<para> +This is the primary web site for &kde;-related multimedia information. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><ulink +url="http://www.arts-project.org">http://www.arts-project.org</ulink></term> +<listitem> +<para> +This is the home page for the &arts; project. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>&kde; 2.0 Development</term> +<listitem> +<para> +Chapter 14 of this published book covers multimedia, including +&arts;. It is available in print or on-line with annotations at <ulink +url="http://www.andamooka.org/">http://www.andamooka.org</ulink>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<ulink +url="http://sound.condorow.net">http://sound.condorow.net</ulink></term> +<listitem> +<para> +This site has a comprehensive listing of sound and &MIDI; applications +for &Linux;. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</chapter> diff --git a/doc/artsbuilder/tools.docbook b/doc/artsbuilder/tools.docbook new file mode 100644 index 00000000..417951df --- /dev/null +++ b/doc/artsbuilder/tools.docbook @@ -0,0 +1,735 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> + +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-tools"> +<title>&arts; Tools</title> + +<para> +Included with &arts; is a number of utilities for controlling and +configuring its behavior. You need to have some familiarity with most of +these tools in order to use &arts; effectively. This section describes +each of the utilities and their command options. +</para> + +<sect1 id="kde-control-center"> +<title>&kcontrol;</title> + +<para> +When running &arts; under &kde;, the &kcontrolcenter; provides a group +of control panel settings under the <guilabel>Sound</guilabel> +category. Some of these settings are used by &arts;. You can also +associate sounds with various window manager and &kde; events using the +<menuchoice><guilabel>Look & Feel</guilabel><guilabel>System +Notifications</guilabel></menuchoice> panel. See the &kcontrol; manual +for information on using the panel settings. +</para> + +</sect1> + +<sect1 id="artsd"> +<title>&artsd;</title> + +<para> +Access to the sound hardware resources is controlled by &artsd;, the +&arts; daemon. This allows different applications to simultaneously send +requests to the server, where they can be mixed together and +played. Without a centralized sound server a single application using a +sound device would prevent other applications from using it. +</para> + +<para> +To use &arts; there should be one and only one copy of &artsd; +running. It is typically run when &kde; starts up if it is enabled in +the &kcontrol; <guilabel>Sound Server</guilabel> panel. +</para> + +<para>The program accepts the following arguments:</para> + +<!-- LW: FIX THIS --> + +<cmdsynopsis> +<command>artsd</command> +<group choice="opt"> +<option>-n</option> +<option>-p</option> +<option>-N</option> +<option>-W <replaceable>n</replaceable></option> + +</group> +<group choice="opt"> +<option>-a <replaceable>audiomethod</replaceable></option> +<option>-r <replaceable>sampling rate</replaceable></option> +<option>-b <replaceable>bits</replaceable></option> +<option>-d</option> +<option>-D <replaceable>devicename</replaceable></option> +<option>-F <replaceable>fragments</replaceable></option> +<option>-S <replaceable>size</replaceable></option> +<option>-s <replaceable>seconds</replaceable></option> +<option>-m <replaceable>appName</replaceable></option> +</group> +<group choice="opt"> +<option>-h</option> +<option>-A</option> +<option>-v</option> +<option>-l <replaceable>level</replaceable></option> +</group> +</cmdsynopsis> + +<variablelist><varlistentry> +<term><option>-r <replaceable>sampling rate</replaceable></option></term> +<listitem> +<para>Set sampling rate to use.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-h</option></term> +<listitem> +<para>Display command usage.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-n</option></term> +<listitem> +<para>Enable network transparency.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-p <replaceable>port</replaceable></option> +</term> +<listitem> +<para>Set <acronym>TCP</acronym> port to use (implies +<option>-n</option>).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-u</option></term> +<listitem> +<para>Public, no authentication (dangerous).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-d</option></term> +<listitem> +<para>Enable full duplex operation.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>-D <replaceable>device name</replaceable></option></term> +<listitem> +<para>Specify audio device (usually <filename>/dev/dsp</filename>).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-F <replaceable>fragments</replaceable></option></term> +<listitem> +<para>Set number of fragments.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-S <replaceable>size</replaceable></option></term> +<listitem> +<para>Set fragment size, in bytes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-s <replaceable>seconds</replaceable></option></term> +<listitem> +<para>Set server auto-suspend time, in seconds. A value of zero +disables auto-suspend.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-m <replaceable>appName</replaceable></option></term> +<listitem> +<para>Specify the name of an application to be used to display error, +warning, and informational messages. If you are running KDE you can +use the <application>artsmessage</application> utility for this.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-N</option></term> +<listitem> +<para> +Increase the size of network buffers to a value suitable for running over +a 10 mbps LAN. This is equivalent to using the -w 5 option (see below). +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>-w <replaceable>n</replaceable></option></term> +<listitem> +<para> +When running <application>artsd</application> over a network connection +to another host you typically want to use a larger buffer size to +avoid dropouts. ARts provides applications with a suggested minimum +buffer size. Without this option the default size is based on the +fragment size * fragment count. Using this option you can increase +the size from the default by a factor of <replaceable>n</replaceable>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-l <replaceable>level</replaceable></option></term> +<listitem> +<para>Set information level - 3 (quiet), 2 (warnings), 1 (info), 0 +(debug).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-v</option></term> +<listitem> +<para>Display version level.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para> +In most cases simply running &artsd; will suffice. +</para> +</sect1> + +<sect1 id="artswrapper"> +<title>&artswrapper;</title> + +<para> +To provide good real-time response, &artsd; is usually run as a +real-time process (on platforms where real-time priorities are +supported). This requires <systemitem class="username">root</systemitem> +permissions, so to minimize the security implications, &artsd; can be +started using the small wrapper program &artswrapper; which simply sets +real-time priority (running as <systemitem +class="username">root</systemitem>) and then executes &artsd; as a +non-<systemitem class="username">root</systemitem> user. +</para> + +<para>If you make artswrapper SUID <systemitem +class="username">root</systemitem>, it will likely improve the quality +of your audio playback by reducing gaps in the music. However, it +also increases the risk that a bug in the code or a malicious user can +crash or otherwise harm your machine. In addition, on multi-user +machines, prioritizing high-quality audio may result in deteriorated +performance for the users who are trying to make +<quote>productive</quote> use of the machine.</para> + +</sect1> + +<sect1 id="artsshell"> +<title>&artsshell;</title> + +<para> +The &artsshell; command is intended as a utility to perform +miscellaneous functions related to the sound server. It is expected that +the utility will be extended with new commands in the future (see the +comments in the source code for some ideas). +</para> + +<para> +The command accepts the following format: +</para> + +<!-- LW: FIX THIS --> + +<cmdsynopsis> +<command>artsshell</command> +<group> +<arg>suspend</arg><arg>status</arg> +<arg>terminate</arg> +<arg>autosuspend <replaceable>secs</replaceable></arg> +<arg>networkbuffers <replaceable>n</replaceable></arg> +<arg>volume [<replaceable>volume</replaceable>]</arg> +<arg>stereoeffect <replaceable>options</replaceable></arg> +</group> +<group> +<option>-h</option> +<option>-q</option> +</group> +</cmdsynopsis> + +<para>artsshell [options] <replaceable>command</replaceable> [<replaceable>command-options</replaceable>] </para> + +<para> +The following options are supported: +</para> + +<variablelist> + +<varlistentry> +<term><option>-q</option></term> +<listitem> +<para>Suppress all output.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-h</option></term> +<listitem> +<para>Display command usage.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>The following commands are supported:</para> + +<variablelist> + +<varlistentry> +<term><option>suspend</option></term> +<listitem> +<para> +Suspend the sound server. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>status</option></term> +<listitem> +<para>Display sound server status information.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>terminate</option></term> +<listitem> +<para> +Terminate the sound server. This may confuse and/or crash any +applications that are currently using it. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>autosuspend</option> <parameter>seconds</parameter></term> +<listitem> +<para> +Set the autosuspend time to the specified number of seconds. The sound +server will suspend itself if idle for that period of time. A value of +zero disables auto-suspend. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>networkbuffers</option> <parameter>n</parameter></term> +<listitem> +<para> +Set the size of the network buffers to be a factor of +<parameter>n</parameter> times the default size. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>volume</option> [<replaceable>volume</replaceable>]</term> +<listitem> +<para> +Sets volume scaling for sound server audio output. The +<replaceable>volume</replaceable> argument is a floating point +value. With no argument the current volume is displayed. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>stereoeffect list</option></term> +<listitem> +<para>List all of the available stereo effect modules.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>stereoeffect insert [top|bottom]</option> <replaceable>name</replaceable></term> +<listitem> +<para>Insert a stereo effect into the stereo effect stack. Returns +an identifier that can be used for later removing it. It can be +installed at the top or the bottom (the default).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>stereoeffect remove</option> <replaceable>id</replaceable></term> +<listitem> +<para>Removes the stereo effect with identifier +<replaceable>id</replaceable> from the effects stack.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="artsplay"> +<title><application>artsplay</application></title> + +<para>The <application>artsplay</application> command is a simple utility to +play a sound file. It accepts a single argument corresponding to the name of a +sound file which is sent to the sound server to be played. The sound +file can be any common sound file type such as <literal +role="extension">wav</literal> or <literal +role="extension">au</literal>. This utility is good for testing that the +sound server is working. By running two commands in parallel or in rapid +succession you can demonstrate how the sound servers mixes more than one +sound source.</para> + +</sect1> + +<sect1 id="artsdsp"> +<title><application>artsdsp</application></title> + +<para> +The sound server only supports applications that are &arts;-aware. Many +legacy applications want to access the sound device directly. The +&artsdsp; command provides an interim solution that +allows most of these applications to run unchanged. +</para> + +<para> +When an application is run under &artsdsp; all accesses to the <filename +class="devicefile">/dev/dsp</filename> audio device are intercepted and +mapped into &arts; <acronym>API</acronym> calls. While the device +emulation is not perfect, most applications work this way, albeit with +some degradation in performance and latency. +</para> + +<para>The &artsdsp; command follows the format: +</para> + +<!-- LW: FIX THIS --> +<para> +artsdsp [<replaceable>options</replaceable>] <replaceable>application arguments</replaceable> +</para> + +<para> +The following options are recognized: +</para> + +<variablelist> + +<varlistentry> +<term><option>-h</option>, <option>--help</option></term> +<listitem> +<para>Show brief help.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>-n</option> <option>--name</option> = <replaceable>name</replaceable></term> +<listitem> +<para>Use <replaceable>name</replaceable> to identify player to <command>artsd</command>.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-m</option> <option>--mmap</option></term> +<listitem> +<para>Emulate memory mapping (⪚ for <application>Quake</application>).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-v</option> <option>--verbose</option></term> +<listitem> +<para>Show parameters.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para> +A typical invocation is: +</para> + +<para> +<userinput><command>artsdsp</command> <option>-v</option> <option>-m</option> <parameter>realplay <replaceable>song.mp3</replaceable></parameter></userinput> +</para> + +<para> +Some applications work better with the <option>--mmap</option> +option. Not all features of the sound device are fully emulated, but +most applications should work. If you find one that does not, submit a +detailed bug report and the developers may be able to fix it. Again, +remember this is an interim solution and something of an ugly hack; the +best solution is to add native &arts; support to the applications. If +your favorite sound application does not have &arts; support, ask the +developer to provide it. +</para> + +</sect1> + +<sect1 id="artscat"> +<title><application>artscat</application></title> + +<para> +This is a simple utility to send raw audio data to the sound server. +You need to specify the data format (sampling rate, sample size, and +number of channels). This is probably not a utility that you will use +often, but it can be handy for testing purposes. The command syntax is: +</para> + +<!-- LW: FIX THIS --> + +<para> +artscat [ <replaceable>options</replaceable> ] [ <replaceable>filename</replaceable> ] +</para> + +<para> +If no file name is specified, it reads standard input. The following +options are supported: +</para> + +<variablelist> +<varlistentry> +<term><option>-r</option> <parameter>sampling +rate</parameter></term> +<listitem> +<para> +Set the sampling rate to use. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-b</option> <parameter>bits</parameter></term> +<listitem> +<para> +Set sample size to use (8 or 16). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-c</option> <parameter>channels</parameter></term> +<listitem> +<para> +Set number of channels (1 or 2). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-h</option></term> +<listitem> +<para> +Display command usage and exit. +</para> +</listitem> +</varlistentry> + +</variablelist> +</sect1> + +<sect1 id="artscontrol"> +<title>&artscontrol;</title> + +<para> +This is a graphical utility for performing a number of tasks related to +the sound server. The default window displays two volume level +indicators and a slider to control overall output volume. From the +<guimenu>View</guimenu> menu you can select other functions: +</para> + +<variablelist> + +<varlistentry> +<term><guimenuitem>FFT Scope</guimenuitem></term> +<listitem> +<para> +Opens a window which shows a real-time spectrum analyzer style display. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Audio Manager</guimenuitem></term> +<listitem> +<para> +Displays active sound sources and allows you to connect them to any of +the available busses. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>aRts Status</guimenuitem></term> +<listitem> +<para> +Shows if the sound server is running and if scheduling is +real-time. Indicates when server will autosuspend and allows you to +suspend it immediately. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Midi Manager</guimenuitem></term> +<listitem> +<para> +Shows active &MIDI; inputs and outputs and allows you to make connections +[TODO: Does this work yet? Need more detail]. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>FreeVerb</guimenuitem></term> +<listitem> +<para> +Connects a FreeVerb reverb effect to the stack of &arts; output effects +and allows you to control the effect parameters graphically. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Leds-like volume display</guimenuitem></term> +<listitem> +<para> +Changes the volume indicators in the main window to use a colored +<acronym>LED</acronym> display format instead of progress bars. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="artsc-config"> +<title><application>artsc-config</application></title> + +<para> +This is a utility to assist developers using the &arts; C +<acronym>API</acronym>. It outputs the appropriate compiler and linker +options needed when compiling and linking code with &arts;. It is +intended to be used within make files to assist in portability. The +command accepts three options: +</para> + +<variablelist> +<varlistentry> +<term><option>--cflags</option></term> +<listitem> +<para> +Displays the compiler flags needed when compiling with the &arts; C +<acronym>API</acronym>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>--libs</option></term> +<listitem> +<para> +Displays the linker flags needed when linking with the &arts; C +<acronym>API</acronym>. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><acronym>--version</acronym></term> +<listitem> +<para> +Displays the version of the <command>artsc-config</command> command. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Typical output from the command is shown below:</para> + +<screen width="40"> +<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--cflags</option></userinput> +<computeroutput>-I/usr/local/kde2/include/artsc</computeroutput> +<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--libs</option></userinput> +<computeroutput>-L/usr/local/kde2/lib -ldl -lartsc -DPIC -fPIC -lpthread</computeroutput> +<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--version</option></userinput> +<computeroutput>0.9.5</computeroutput> +</screen> + +<para> +You could use this utility in a make file using a rule such as: +</para> + +<programlisting> +artsc: artsc.c + gcc `artsc-config --cflags` -o artsc artsc.c `artsc-config --libs` +</programlisting> + +</sect1> + +<sect1 id="mcopidl"> +<title>&mcopidl;</title> + +<para> +The &mcopidl; command is the &IDL; file compiler for &MCOP;, the +Multimedia Communication Protocol used by &arts;. Interfaces in &arts; +are defined in &IDL;, a language independent Interface Definition +Language. The &mcopidl; utility accepts an &IDL; file as input and +generates C++ header and source files for a class implementing the +interface. The command accepts the following syntax: +</para> + +<!-- LW: FIX THIS --> + +<para>mcopidl [ <replaceable>options</replaceable> ] <replaceable>filename</replaceable> +</para> + +<para>The valid options are:</para> +<variablelist> +<varlistentry> +<term><option>-I</option> <parameter>directory</parameter></term> +<listitem> +<para> +Search in <parameter>directory</parameter> for includes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-e</option> <parameter>name</parameter></term> +<listitem> +<para> +Exclude a struct, interface, or enum type <parameter>name</parameter> +from code generation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-t</option></term> +<listitem> +<para> +Also create <literal role="extension">.mcoptype</literal>/<literal +role="extension">.mcopclass</literal> files containing type information +for the &IDL; file. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +More information about &MCOP; and &IDL; is covered in the section <link +linkend="interfaces">Interfaces and &IDL;</link>. +</para> + +</sect1> + +</chapter> diff --git a/doc/juk/Makefile.am b/doc/juk/Makefile.am new file mode 100644 index 00000000..171f575c --- /dev/null +++ b/doc/juk/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/juk/history-playlist.png b/doc/juk/history-playlist.png Binary files differnew file mode 100644 index 00000000..c80ee792 --- /dev/null +++ b/doc/juk/history-playlist.png diff --git a/doc/juk/index.docbook b/doc/juk/index.docbook new file mode 100644 index 00000000..28763a3d --- /dev/null +++ b/doc/juk/index.docbook @@ -0,0 +1,1665 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY package "kdemultimedia"> + <!ENTITY kappname "&juk;"> + <!ENTITY juk "<application>JuK</application>"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &juk; Handbook</title> + +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<author> +<firstname>Michael</firstname> +<surname>Pyne</surname> +<affiliation> +<address><email>michael.pyne@kdemail.net</email></address> +</affiliation> +</author> + +<othercredit role="developer"> +<firstname>Scott</firstname> +<surname>Wheeler</surname> +<affiliation> +<address>&Scott.Wheeler.mail;</address> +</affiliation> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2001</year> +<year>2002</year> +<year>2004</year> +<holder>&Scott.Wheeler;</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-05-06</date> +<releaseinfo>2.1</releaseinfo> + +<abstract> +<para> +&juk; is a jukebox, tagger and music collection manager. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdemultimedia</keyword> +<keyword>audio</keyword> +<keyword>tagger</keyword> +<keyword>player</keyword> +<keyword>jukebox</keyword> +<keyword>JuK</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&juk; is, well, a jukebox. As is typical with many jukebox +applications, &juk; allows you to edit the <quote>tags</quote> of your +audio files, and manage your collection and playlists. +</para> +</chapter> + +<chapter id="using-juk"> +<title>Using &juk;</title> + +<para> +<screenshot> +<screeninfo>Here's a screenshot of &juk;</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="juk-main.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot of &juk; in action.</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<para>&juk; maintains a list of all files that it knows about. This +is called the <guilabel>Collection List</guilabel>. The collection +list is specific to &juk; and is not shared with other +applications.</para> + +<para>Independent of the Collection List, are playlists. You can have +as many playlists as you want. You can use &juk; created playlists +with other media players (such as &noatun; or +<application>xmms</application>) and you can manage playlists created +in those applications from within &juk;.</para> + +<para>You can add files to the Collection List individually, using +<menuchoice><guimenu>File</guimenu><guimenuitem>Open +File...</guimenuitem></menuchoice> and selecting them from a standard +&kde; file dialog. You can add entire folders using +<menuchoice><guimenu>File</guimenu><guimenuitem>Open +Folder...</guimenuitem></menuchoice>. Folders added this way +will be rescanned every time you start &juk; +<!-- ask scott: + Asked 2004-04-27 (mpyne), Choosing Reload from the Collection + List context menu will result in a rescan. Also, a KDirWatch + watches the folders, but is apparently not recursive. --> +. You can force the folders to be rescanned by right-clicking on the <guilabel>Collection List</guilabel> +icon, and selecting <guimenuitem>Reload</guimenuitem>.</para> + +<para>Adding a song to a playlist will automatically add its file to +the Collection List, but adding a file to the Collection List won't +automatically add the song to any playlists.</para> + +<para>You can quickly create a playlist from your entire Collection +List, by &RMB; clicking on the <guilabel>Collection List</guilabel> +icon, and choosing <guimenuitem>Duplicate</guimenuitem>. The +resulting playlist is a normal playlist, and editing it will not +affect the <guilabel>Collection List</guilabel>.</para> + +<para>You can add playlist files created outside &juk; individually by +selecting them with +<menuchoice><guimenu>File</guimenu><guimenuitem>Open +File...</guimenuitem></menuchoice>. Any playlist files found in +folders you add with +<menuchoice><guimenu>File</guimenu><guimenuitem>Open +Folder...</guimenuitem></menuchoice> will also be added +automatically.</para> + +<para>You can create a new playlist by choosing +<menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice> +or the <guiicon>New</guiicon> icon on the toolbar. You will be +prompted for a name, and then an icon for that playlist will appear in +the playlist pane. You can now drag and drop files from the +Collection List, or from other playlists, to your playlist. Use the <guiicon>Save</guiicon> +icon or +<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> to +save the playlist at any time.</para> + +<sect1 id="collection-list-gui"> +<title>The Song List</title> + +<para>When you are viewing the Collection List, the main pane contains +all the files that &juk; knows about. When you are viewing a +playlist, only the songs that are in that playlist are shown. In +either case, the appearance and behavior of the list is the +same.</para> + +<para>Each song takes one row in the display. There is a column for +each metadata field that &juk; tracks. These columns correspond to +the fields available to edit in the tag editor.</para> + +<para>You can reorder the list at any time by &LMB; clicking on the +column header. This will first sort the files in ascending order +based on the contents of that column. If you &LMB; click again on the +same header, the files will be re-sorted in descending order.</para> + +<para>The columns are initially sized wide enough to show the longest +entry available. You can resize the columns by placing your mouse +cursor on the divider between two columns. When the cursor changes +from a pointer, &LMB; click and drag in the direction you want to +resize the columns.</para> + +<para>You can reorder the columns by &LMB; clicking on a header and +dragging the header to the left or right. You cannot drag past the +edge of the window when doing this however, so you may need to scroll +a little to the left or right, and repeat dragging the header, until +you have placed it in your preferred position.</para> + +<para>You can hide or unhide columns by &RMB; clicking on a column header, +and clicking on the name of the column to change.</para> + +<para>&LMB; double clicking on a file will play it with the built-in +player. If another song was already playing, it will stop, and the +new song will play.</para> + +<para>&RMB; clicking on a file offers you several options:</para> + +<variablelist> +<varlistentry> +<term><guimenuitem>Play Next</guimenuitem></term> +<listitem> +<para>This will start playing the file as soon as the current +song is over. If no song is playing, the file will be played when +you next hit the <guiicon>Play</guiicon> button. If you have already +chosen the Play Next option on a different file, then this file will +override that selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Cut</guimenuitem></term> +<term><guimenuitem>Copy</guimenuitem></term> +<term><guimenuitem>Paste</guimenuitem></term> +<listitem> +<para>...</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Clear</guimenuitem></term> +<listitem> +<para>If you are viewing the Collection List, choosing +<guimenuitem>Clear</guimenuitem> will remove the file from the list, +and will also remove all corresponding entries for this song from all +playlists. You should note that if this file is in a folder that +&juk; scans on startup, it will be readded to the Collection List the +next time you start up &juk; but it won't be automatically added to +any playlists.</para> +<para>If you are viewing a playlist, <guimenuitem>Clear</guimenuitem> +will simply remove the song from the playlist.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Edit</guimenuitem></term> +<listitem> +<para>Will allow you to edit the currently highlighted song, in the +column you clicked in. For example, if you do not have the tag editor +visible, and you are busy creating a playlist, but you notice a +mis-spelling in an artist name, you can edit it directly with this +menu item.</para> +<para>Changes made in this manner are always saved immediately as soon +as you click elsewhere and are finished editing.</para> +<para>This menu item will be disabled if &juk; detects that the track you +have selected is read-only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Refresh Items</guimenuitem></term> +<listitem> +<para>This will reload the tag information of the selected files, in +case the files have been changed while &juk; was running.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Remove From Disk</guimenuitem></term> +<listitem> +<para>This will remove the file from the Collection List, remove all +entries for the song in all playlists, and delete the file from your +disk. You cannot undo this, although you will be asked to confirm +your choice. Use this with caution.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guisubmenu>Guess Tag Information</guisubmenu></term> +<listitem> +<para>This will make &juk; try to guess information such as the +Artist and Title of a song. &juk; employs different methods of guessing: + <variablelist> + + <varlistentry><term><guimenuitem>From File Name</guimenuitem></term> + <listitem><para>&juk; will try to guess the tags of the song based on its filename. + For example, a song name such as <filename>Roxette - You've Got the Look.mp3</filename> + would guess Roxette for the artist and You've Got the Look as the title. You + can adjust the way &juk; guesses for tags by selecting <menuchoice><guimenu>Settings + </guimenu><guimenuitem>Tag Guesser...</guimenuitem></menuchoice>, which will open the + <link linkend="juk-tag-guesser-configuration">Tag Guesser dialog</link>. &juk; will not + replace tags that it did not guess from the file name.</para> + </listitem> + </varlistentry> + + <varlistentry><term><guimenuitem>From Internet</guimenuitem></term> + <listitem><para>&juk; will try to guess the tags of the song by using the + MusicBrainz program. You must have MusicBrainz installed for this command to work. + </para> + </listitem> + </varlistentry> + + </variablelist> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Rename File</guimenuitem></term> +<listitem> +<para>This will rename the selected files to conform to a given format. You must +choose the way you want the files renamed first by selecting <menuchoice> +<guimenu>Settings</guimenu><guimenuitem>File Renamer...</guimenuitem></menuchoice>. +The resulting name of each file is based on its metadata tags. For example, +the Ogg Vorbis song <quote>The Theme (Metroid)</quote> by Stemage could result in +<filename>/usr/share/music/Stemage/The Theme (Metroid).ogg</filename>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Create Playlist From Selected Items</guimenuitem></term> +<listitem> +<para>This allows you to quickly create a playlist from songs in your Collection List. +This function will prompt you for a name for the new playlist, and will then insert all of +the songs that are selected into the new playlist.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Add Selected Items to K3b Project</guimenuitem></term> +<listitem> +<para>This allows you to quickly create a K3b &CD;-burning project from your selected songs. &juk; will ask you if you would like an Audio &CD; project or a Data &CD; project, unless K3b already has a project open.</para> + +<para>If K3b is not already running, &juk; will start it up for you. After that, &juk; will add your selected files to the current K3b project. You can then save the project in K3b for burning later, or burn the &CD; right away. +</para> + +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="juk-playlists"> +<title>&juk; Playlists</title> +<para>A playlist is simply a collection of songs grouped by some category. For example, you +may have a playlist of songs that you listen to while coding, while trying to sleep, or even +when you need a laugh. &juk; supports several different types of playlists. +</para> + +<variablelist> + +<varlistentry> +<term id="juk-normal-playlists">Normal playlists</term> +<listitem><para><inlinemediaobject><imageobject><imagedata format="PNG" fileref="normal-playlist.png"/></imageobject></inlinemediaobject> +This is the most common kind of playlist. It is a playlist composed of files, just +like the Collection List.</para></listitem> +</varlistentry> + +<varlistentry> +<term id="juk-history-playlists">The history playlist</term> +<listitem><para><inlinemediaobject><imageobject><imagedata format="PNG" fileref="history-playlist.png"/></imageobject></inlinemediaobject> +If you enable this playlist (by enabling <menuchoice><guimenu>View</guimenu><guimenuitem>Show History</guimenuitem></menuchoice>, +this playlist will record every song that &juk; plays. The playlist will have an extra column, <guilabel>Time</guilabel>, which +records the exact time and date the song played. The playlist doesn't start tracking the history until it is enabled, however. +</para></listitem> +</varlistentry> + +<varlistentry> +<term id="juk-search-playlists">Search playlists</term> +<listitem><para><inlinemediaobject><imageobject><imagedata format="PNG" fileref="search-playlist.png"/></imageobject></inlinemediaobject> +This is a playlist which is based off of a search. You can create a playlist like this by clicking <menuchoice> +<guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Search Playlist</guimenuitem></menuchoice>, or by clicking on the +<link linkend="juk-advanced-search-dialog">Advanced Search</link> + button on the <link linkend="search-bar">Search Bar</link>.</para> +<para>After creating this playlist, it will keep track of which songs in the Collection List match your criteria, and automatically update itself accordingly whenever the +Collection List changes.</para></listitem> +</varlistentry> + +</variablelist> + +<para>Playlists are organized in the <guilabel>Playlist pane</guilabel>, which is the vertical bar at the left. In this pane is an icon +for every playlist you have. There are different view mode for this pane, which can be selected from the +<guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu> menu. + +<variablelist> + +<varlistentry> +<term id="juk-viewmode-default">Default View mode</term> +<listitem> +<para> +This is the default view mode. In this mode, all the playlists are shown as large icons, one above the other in the view mode. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="juk-viewmode-compact">Compact View mode</term> +<listitem> +<para> +This mode is similar to the Normal Viewmode, with the exception that the playlists are represented with horizontal bars with small icons instead +of with square boxes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="juk-viewmode-tree">Tree View mode</term> +<listitem> +<para>This mode is the most powerful. This mode is just like the Compact viewmode, except that the Collection List is now the root of a tree of virtual +playlists. The Collection List has three children nodes, Artist, Album, and Genre. Each of these node has children representing all of the entries +from that specific category. For example, if your Collection List contains music from 4 different artists, you would have 4 entries under the artist +node.</para> +<para>One nifty feature of the tree view mode is something called drag-and-drop retagging. Simply select some files in the track list, and drag them +onto one of the artist, album, or genre nodes under Collection List. The songs will automatically be retagged to match the item you dropped the +tracks on. For example, if you drag a group of tracks onto a Genre called "Rock", all of the tracks will be retagged will a Genre tag of Rock. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</para> + +</sect1> + +<sect1 id="juk-tagger"> +<title>The &juk; Tag Editor</title> + +<para>For many file formats, it is practical to use the filename to +describe the contents of the file: <quote><filename>Report for the +board - June 2003.doc</filename></quote> for example, may be all the +information you need in order to find that file again. Trying to +capture all the useful information about a particular song however, +could lead to filenames like this: <quote><filename>Type O Negative - +The Glorious Liberation Of The Peoples Technocratic Republic Of +Vinnland By The Combined Forces Of The United Territories Of +Europa.mp3</filename></quote> or <quote><filename>Various +Artists_15_The Smithsonian Collection of Classic Jazz Volume II_Jimmie +Lunceford & His Orchestra - Organ Grinder's +Swing.mp3</filename></quote>. These are neither very practical to +use, nor do they contain all of the useful information that you might +have collected about the song. Adding the album, and track number, +for example, to the first would make it even longer and more +unmanageable, while still not telling you at a glance the year it was +released, or what style of music it is, if you're not familiar with +the artist.</para> + +<para>The solution then, is to store this kind of metadata inside the +files themselves. Mp3 and ogg files can also contain small snippets of +text which you can use to describe the content of the file. There are +several formats, but &juk; hides the details of the differences +between them, and provides a standard way to edit a standard subset of +well known tags for all your audio files.</para> + +<para>&juk;'s full featured tag editor allows you to edit the tags in +both mp3 and ogg files. You can edit single files or multiple files, +and you can select a mix of mp3 and ogg files to edit. The only +requirement is that you have write access to the files themselves; you +cannot edit the tags of a file that is mounted from a &CD-ROM; for +example.</para> + +<sect2 id="tagging-a-single-file"> +<title>Editing the Tags in a Single File</title> + +<para>To edit the tag in a single file, select it in either the +collection list or any entries it has in any playlist. If the tag +editor is not visible, enable it by choosing +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Tag +Editor</guimenuitem></menuchoice>. The tag editor displays in the +bottom of the list view.</para> + +<para>Simply type into any of the editable fields to change the +information. When you are done, &LMB; click back in the list, and you +will be prompted to save your changes.</para> + +<para>You may find that the tag editor remains disabled when you've +clicked on a file. This happens when &juk; has detected that the track +is read-only.</para> + +<variablelist> +<title>Tag Editor Fields</title> +<varlistentry> +<term><guilabel>Artist Name:</guilabel></term> +<listitem> +<para>The name of the Artist(s) who released the song.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Track name:</guilabel></term> +<listitem> +<para>The name of the song.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Album name:</guilabel></term> +<listitem> +<para>The name of the album the song was released on.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Genre:</guilabel></term> +<listitem> +<para>The <quote>Style</quote> of the music. &juk; provides a list +corresponding roughly to the informal id3 standard, but you are free +to type your own entries in this list.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>File name:</guilabel></term> +<listitem> +<para>The file name of the actual file on disk. You can edit this +directly, and when you save, the file will be renamed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Track:</guilabel></term> +<listitem> +<para>The position of the track on the original recording.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Year:</guilabel></term> +<listitem> +<para>The year the song was released.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Length:</guilabel></term> +<listitem> +<para>This is not editable, it is simply shown for information.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bitrate:</guilabel></term> +<listitem> +<para>This is not editable, it is simply shown for information.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Comment:</guilabel></term> +<listitem> +<para>You can add your own free text comment here, with additional +notes &etc;</para> +</listitem> +</varlistentry> +</variablelist> + +<para>You can explicitly and immediately save your changes at any time +using the +<menuchoice><guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem></menuchoice> +menu entry or by pressing +<keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo>.</para> + +</sect2> + +<sect2 id="tagging-multiple-files"> +<title>Editing the Tags in Multiple Files</title> + +<para>You can select multiple files in the list view, and edit one or +more fields in the tags for all files at once.</para> + +<para>Use <keycap>Shift</keycap> and the &LMB; to select a contiguous +list of files, and &Ctrl; and &LMB; to select individual +non-contiguous files.</para> + +<para>If the tag editor is not visible, you can enable it by choosing +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Tag +Editor</guimenuitem></menuchoice>. The tag editor displays in the +bottom of the list view.</para> + +<para>The tag editor behaves slightly differently when you have +selected multiple files.</para> + +<para>Each field in the tag editor will now show an +<guilabel>Enable</guilabel> check box next to it. Any field that has +exactly the same contents for all the files you selected, displays +that content, and is enabled for editing, with the +<guilabel>Enable</guilabel> check box checked.</para> + +<!-- put screeny here --> + +<para>Any field that does not have matching contents in all selected +files is not initially editable, and does not display any contents at +all.</para> + +<para>To change the content of any field, check the +<guilabel>Enable</guilabel> check box if it is not already checked, and +edit the field as you normally would.</para> + +<para>When you are done, &LMB; click back in the list view and you +will be prompted to save your changes. The prompt dialog will show +you a list of the affected files, so you have a chance to check that +you are indeed altering the files you intended to.</para> + +<para>You can explicitly and immediately save your changes at any time +using the +<menuchoice><guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem></menuchoice> +menu entry or by pressing +<keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo>.</para> + +</sect2> + +</sect1> + +<sect1 id="juk-rename-dialog"> +<title>The Rename File dialog</title> +<para> +<screenshot> +<screeninfo>The Rename File dialog</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="juk-file-renamer.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot of the Rename File dialog.</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<para>The File Renamer Configuration dialog box is used to configure the +Rename File action, which renames a song's based on the information contained +within its metadata tags. First the tags are altered according to the different +tokens you can alter, and then the tokens are used to generate the filename +according to the <guilabel>Filename scheme</guilabel>. +</para> + +<para>The most important part of the dialog is the <guilabel>Filename +scheme</guilabel> section. You can type a file name scheme here which &juk; +will use to rename the files. The way it works is that some characters are +special. +</para> + +<para><variablelist> +<varlistentry> +<term>%t</term> +<listitem><para>This will be replaced with the Title token upon evaluation.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%a</term> +<listitem><para>This will be replaced with the Artist token upon evaluation.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%A</term> +<listitem><para>This will be replaced with the Album token upon evaluation.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%T</term> +<listitem><para>This will be replaced with the Track token upon evaluation.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%c</term> +<listitem><para>This will be replaced with the Comment token upon evaluation.</para> +</listitem> +</varlistentry> + +</variablelist> +</para> + +<para>Every token can contain %s, which is replaced with the actual tag, +and any text you want, including slashes (/). If a token has a slash, then +that will indicate a folder separator. Of course, it would be possible to +simply type folder separators in the <guilabel>Filename scheme</guilabel> +line.</para> + +<para>Using the tokens, however, allows us to completely ignore tags that are empty. +If you check the <guilabel>Need value</guilabel> check box, then the token will be +ignored if the corresponding tag is empty. For example, you could use this to separate +files with comments from those without by placing something such as +<replaceable>has-comment/%s</replaceable> in the <guilabel>Comment token</guilabel> +editor.</para> + +<para>You can test your filename scheme by using the <guilabel>Current filename</guilabel> editor +at the bottom of the dialog. Type in a filename of a music file, and the <guilabel>New +filename</guilabel> area will display would &juk; would rename the file as given the current +settings. +</para> +</sect1> + +<sect1 id="juk-tag-guesser-configuration"> +<title>The Tag Guesser Configuration dialog</title> +<para> +<screenshot> +<screeninfo>The Tag Guesser Configuration dialog</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="juk-tag-guesser.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot of the Tag Guesser Configuration dialog.</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<para>The Tag Guesser Configuration dialog is used to configure the +Guess from Filename command.</para> + +<para>In the dialog you will see a list on the left of different filename scheme patterns. +&juk; includes an extensive set of defaults patterns to match most common filenaming styles. +If you'd like to add a new scheme, click on the <guibutton>Add</guibutton> button, and type +in your scheme and click on <guibutton>OK</guibutton>. You may use the same percent +tokens as defined in the <link linkend="juk-rename-dialog">Rename Dialog Configuration</link>. +</para> + +<para>&juk; will try the schemes you have listed one at a time, starting at the top of the list. +The first scheme which results in a match will be the scheme used to guess the song's tags. +Some songs may match more than one scheme. You can make sure that the correct scheme matches +first by selecting the scheme in the list box and then using the arrow buttons to move it to the +top of the list. +</para> + +<para>You can also edit or remove a scheme from the list. Just select the scheme in the list, +and use the <guibutton>Modify</guibutton> button to change the scheme, or the +<guibutton>Remove</guibutton> button to remove the scheme from the list. +</para> +</sect1> + +<sect1 id="juk-advanced-search-dialog"> +<title>The Advanced Search dialog</title> +<para> +<screenshot> +<screeninfo>The Advanced Search dialog</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="juk-adv-search.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot of the Advanced Search Dialog.</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<para>The Advanced Search dialog is used to create <link linkend="juk-search-playlists">Search +Playlists</link>. It allows you create a fine-grained search among the different tags of +your song collection.</para> + +<para>At the top of the dialog, you can type in the name of your search playlist. Then, you +can define your search criteria in the <guilabel>Search Criteria</guilabel> group. +</para> + +<para>The top of the <guilabel>Search Criteria</guilabel> group has two radio buttons, +<guilabel>Match any of the following</guilabel> and <guilabel>Match all of the +following</guilabel>. If you select <guilabel>Match any of the following</guilabel>, then +a match by any of the conditions you define will include the song in the playlist. Otherwise, +every condition you define must match in order to include the song in the playlist. +</para> + +<para>Below the radio buttons are the condition definitions. You can add more conditions +by using the <guibutton>More</guibutton> button, and remove conditions by using the +<guibutton>Fewer</guibutton> button. Any conditions you leave blank are ignored, so you do +not have to use <guibutton>Fewer</guibutton> to eliminate empty conditions. +</para> + +<para>Every condition definition has three parts: The tag chooser list on the left, the +matching style list on the right, and the search text in the middle. The tag chooser +lets &juk; know what tag you want to search for the text in. If you choose the special +tag "<All Visible>", then any tag that you can see in the Collection List listing +is fair game to match the search text. +</para> + +<para>The match style list lets &juk; know which search method to use. +The search methods you can use are as follows: +<variablelist> +<varlistentry> +<term>Normal Matching</term> +<listitem><para>This is the default matching style. It searches for the given +text anywhere in the chosen tag, ignoring case differences. For example a +search for mode in the Artist tag would match Depeche Mode.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Case Sensitive</term> +<listitem><para>This search is just like Normal Matching, except that +the search must match the exact case of the text.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Pattern Matching</term> +<listitem><para>This is the most powerful search method. The search +text you type in will define a regular expression used to search within +the tag. Regular expressions are beyond the scope of this documentation, but +the application &kregexpeditor; can help you form a regular expression. +&juk; uses the &Qt; regular expression style.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +<para>Simply choose the conditions you want to include in your search, and +click <guibutton>OK</guibutton> to create your search playlist! +</para> +</sect1> + +<sect1 id="juk-cover-manager"> + +<title>The &juk; Cover Manager</title> + +<para>&juk; 2.3 (part of &kde; 3.5) includes improved cover management code which introduces some new possibilities for users compared with &juk; 2.2 (which was shipped with &kde; 3.4). It also can change the workflow slightly for you if you are used to the way covers were handled in &juk; 2.2. So first, let's review how things used to be.</para> + +<sect2 id="covers-in-juk-2.2"> +<title>How Covers Worked in &juk; 2.2</title> + +<para>In &juk; 2.2, the cover for a track was strictly tied to its <guilabel>Artist</guilabel> and <guilabel>Album</guilabel> information. Although this proved useful enough, and had a few advantages, it wasn't a great way to organize the covers. If you wanted to use a cover for a different track, you either had to rename the tags in the track, or you had to duplicate the cover, wasting hard disk space. And if your track had no <guilabel>Artist</guilabel> or <guilabel>Album</guilabel> information, &juk; would prevent you from setting a cover since it had no information to go by. It worked, but it could be better.</para> + +</sect2> + +<sect2 id="covers-in-juk-2.3"> + +<title>How Covers work in &juk; 2.3</title> + +<para>In &juk; 2.3, the code was redesigned to add a core component responsible for dealing with cover art. Instead of looking on disk for a picture file with a specific name like &juk; 2.2, the Cover Manager in &juk; 2.3 associates every cover with an identification tag, and then uses the tag with your music. It's still not perfect, but it works, and it can save you time while allowing you to do more.</para> + +<sect3 id="examples-adding-covers"> + +<title>Examples of adding covers</title> + +<para>So just as an example, let's say you wanted to set a cover for tracks you just ripped off of your &CD;. We'll use <quote>Alabama - Greatest Hits III</quote> for the sake of discussion. In &juk; 2.2, you could simply select any one of those tracks, and import a cover from the Internet by right-clicking on that track, and using the <menuchoice><guimenu>Tagger</guimenu> <guisubmenu>Cover Manager</guisubmenu> <guimenuitem>Get Cover From Internet</guimenuitem></menuchoice> command. As a side effect of the way &juk; worked, the cover would then be immediately applied to <emphasis>all</emphasis> of the <quote>Alabama - Greatest Hits III</quote> tracks, <emphasis>whether you wanted that or not</emphasis></para> + +<para>In &juk; 2.3, the procedure is exactly the same, with one exception: You should select all of the tracks you want to apply the cover to first. So you would select all the <quote>Alabama - Greatest Hits III</quote> tracks before using the <menuchoice><guimenuitem>Get Cover From Internet</guimenuitem></menuchoice> command. Or if you only wanted to set cover art to half of the tracks for some reason, you'd only select half the tracks before running the <menuchoice><guimenuitem>Get Cover From Internet</guimenuitem></menuchoice> command. Don't worry about duplicating covers, either: &juk; is smart enough to re-use the same image, so you won't get 14 duplicate <literal role="extension">.png</literal> images cluttering your hard drive.</para> +</sect3> + +<sect3 id="reusing-old-covers"> + +<title>Reusing Old Covers</title> + +<para>But what happens if you forgot to select all the tracks you wanted to tag? You could select them and repeat the process, but that would leave a duplicate cover on your hard drive because &juk; cannot quickly tell that the cover you've found is the same as one you already have. But that's alright, because you can tell &juk; to use the cover from another track.</para> + +<para>There are two ways of doing this:</para> + +<para>1. Open the <guilabel>Cover Manager</guilabel> dialog using the <guimenu>Tagger</guimenu> menu (<menuchoice><guimenu>Tagger Cover</guimenu> <guisubmenu>Manager</guisubmenu> <guimenuitem>Show Cover Manager</guimenuitem></menuchoice>). The Cover Manager will display a list of all the covers &juk; knows about on the right, and after they have loaded you can quickly pare the list down using the search line at the top, or by using the list of Artists on the left. Once you see the cover you want to use, you can drag-and-drop the cover onto a track to apply it. It should happen nearly instantaneously since &juk; is reusing the same cover (and you'll see the cover while you're dragging it as well). Unfortunately, it can take awhile to load the covers in the first place, and the Cover Manager isn't really useful for much else besides.</para> + +<para>2. I prefer to use this method because it's rather easy. All you do is double-click on the track that has the cover you want, in order to start it playing. This will cause its cover to show up in the <interface>Now Playing bar</interface>, and you can drag-and-drop the cover to the track you want to change exactly as you would for the Cover Manager.</para> + +</sect3> + +<sect3 id="dragging-covers"> + +<title>Dragging covers to more than one track at once</title> + +<para>Also note that you can use drag-and-drop to quickly apply covers to more than one track. Just select the tracks you want to apply a cover to, and drag the cover onto any one of the selected tracks.</para> +</sect3> + +<sect3 id="old-covers"> + +<title>What happens to my old covers?</title> + +<para>You may be wondering what &juk; will do if you already have covers from &juk; 2.2. What happens is that &juk; will automatically convert the old covers and merge them into the cover management system.</para> + +<para>Because this is a time consuming process, it does not happen all at once. Instead, the old cover is only converted when the cover needs to be shown on screen. As the conversion process is happening, &juk; will recognize what tracks would have shown the cover being converted, and will automatically apply the new cover to those tracks. The end result is that there should be no visible changes: &juk; will keep the same cover on your tracks that they've always had, except that now you can immediately take advantage of the new cover management features.</para> + +</sect3> +<sect3 id="removing-covers"> + +<title>Removing Covers</title> + +<para>Another side effect is that you can now remove a cover from a track without simultaneously removing it from all other tracks with the same <guilabel>Artist</guilabel> and <guilabel>Album</guilabel>.</para> + +<para>In &juk; 2.3, the Remove Cover command now only removes the covers from the selected tracks. +</para> + +</sect3> +<sect3 id="suggested-use"> + +<title>Suggested Uses:</title> + +<para>1. You can now apply the same cover to tracks with Albums that have <quote>Disc 1</quote>, <quote>Disc 2</quote>, etc, which you couldn't do in &juk; 2.2 without duplicating the cover.</para> + +<para> +2. Applying a generic cover to tracks if you simply must have a cover on every track, or if you have music that wasn't released as an album but fits a genre well. You could make yourself a cover for that type of music and apply it to the songs in question.</para> + +</sect3> +</sect2> +</sect1> + +</chapter> + +<chapter id="toolbar-reference"> +<title>The &juk; Toolbar</title> + +<sect1 id="main-toolbar"> +<title>The Main Toolbar</title> + +<screenshot> +<screeninfo>The &juk; toolbar.</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="toolbar.png" /> +</imageobject> +<textobject> +<phrase>The &juk; toolbar.</phrase> +</textobject> +<caption><para>The &juk; toolbar.</para></caption> +</mediaobject> +</screenshot> + +<para>From left to right in the screenshot above, the icons on the +default toolbar are:</para> + +<variablelist> +<varlistentry> +<term><guiicon>New</guiicon></term> +<listitem><para>Create a new playlist. If you hold down the button, a +menu will pop up allowing you to select the different kinds of playlists +to create. +</para> + <variablelist> + <varlistentry><term><guimenuitem>Empty Playlist...</guimenuitem></term> + <listitem><para>This prompts you for a playlist name, and then inserts it into the + Playlist view. The playlist starts out completely empty.</para></listitem> + </varlistentry> + + <varlistentry><term><guimenuitem>Playlist From Folder...</guimenuitem></term> + <listitem><para>This prompts you for a folder to open, and then creates a playlist + containing the music within the folder and any sub-folders. The name of the created + playlist is the same as the name of the selected folder.</para></listitem> + </varlistentry> + + <varlistentry><term><guimenuitem>Search Playlist...</guimenuitem></term> + <listitem><para>This brings up the Advanced Search Dialog, allowing you to create a + <quote>virtual playlist</quote>. Any songs in your Collection List that match the search + criteria that you specify in the Advanced Search Dialog will be added to the new playlist. + As your Collection List changes, the new playlist will as well. For example, if you create a playlist + of all of your Depeche Mode songs, and then add another Depeche Mode song to your Collection List, + it will show up in the Depeche Mode playlist with no special action required on your part. + </para></listitem> + </varlistentry> + + </variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Open</guiicon></term> +<listitem><para>Add a file to the collection list (if it's active) or +to the currently selected playlist. Adding a file to a playlist will +add it to the collection list automatically, but not vice +versa.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Save</guiicon></term> +<listitem><para>Save the currently selected playlist. To save a tag +you have edited, either select another item, or press <keycombo +action="simul">&Ctrl;<keycap>T</keycap></keycombo> +instead.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Cut</guiicon></term> +<listitem><para>If a playlist or song is selected, cut (remove) it from the +list. If the tag editor is active, this works like cut in any editor, +removing the selected text, but keeping a copy on the +clipboard.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Copy</guiicon></term> +<listitem><para>If the tag editor is active, this works like copy in +any editor, placing a copy of the selected text on the +clipboard.</para> +<para>If you use copy on a song in the collection list, the url is +placed on the clipboard, so you can paste it. For example, you could +paste the url into a text editor, &konqueror;, or another +playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Paste</guiicon></term> +<listitem><para>If you previously either cut or copied a url from the +collection list, you can paste the url back into a new playlist. You +could also paste a url you have copied from &konqueror; or any other +application. If you are operating in the tag editor, paste will paste +any text currently on the clipboard into the selected +field.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Show Search Bar</guiicon></term> +<listitem><para>Show or hide <link linkend="search-bar">the search +bar</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Show Tag Editor</guiicon></term> +<listitem><para>Show or hide <link linkend="tagging-a-single-file">the +tag editor</link>.</para></listitem> +</varlistentry> + +<varlistentry id="play-toolbar"> +<term>Play controls</term> +<listitem> +<para>These work like any standard media player you may have come +across. The controls are <guiicon>Play</guiicon>, +<guiicon>Pause</guiicon>, <guiicon>Stop</guiicon>, <guiicon>Skip to +the previous song</guiicon> and <guiicon>Skip to the next +song</guiicon>.</para> +<para>There is also a tracking bar, showing how far along (relatively) +in the current song you are. You can drag this slider with the mouse +in order to skip forwards or backwards within a track.</para> +<para>Finally there is a volume slider. As you may expect, this +raises and lowers the volume. <quote>Loud</quote> is on the right, +and <quote>Quiet</quote> is on the left.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="search-bar"> +<title>The Search bar</title> + +<para>The search bar allows you to quickly search for a song in the +collection list or a playlist.</para> + +<para>Simply typing text into the search bar will reduce the visible +list of songs to those which contain that text in any visible +column. Pressing <keycap>Enter</keycap> will start playing the top match in the playlist view.</para> + +<para>Searching begins instantly when text is entered into the search +field. Searching is incremental, that is, as you type each character +into the text field, the search is narrowed further. This is useful +to find a song where you only remember part of a name, for +instance.</para> + +<para>If you would like to make a more fine-grained search, you can click +the Advanced Search button to the right of the search bar, which will allow +you to create a virtual playlist. If you would like to cancel the search, +you can simply click on the Clear button to the left of the search bar.</para> + +</sect1> + +</chapter> + +<chapter id="menu-and-command-reference"> +<title>Menu and Command Reference</title> + +<sect1 id="menus"> +<title>Menus</title> + +<sect2 id="menu-file"> +<title><guimenu>File</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Empty Playlist...</guimenuitem> +</menuchoice> +</term> +<listitem><para>Create a new playlist</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Playlist From +Folder...</guimenuitem> +</menuchoice> +</term> +<listitem><para>Creates a new playlist, containing all music files +in a folder and any sub-folders. Any music within playlists files that +&juk; recognizes will also be added.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Search Playlist...</guimenuitem> +</menuchoice> +</term> +<listitem><para>Creates a new <link linkend="juk-search-playlists">search playlist</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem> +</menuchoice> +</term> +<listitem><para>Select a file (or files) to add to the collection list. If you select +a playlist file, every file in the playlist will be added.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Add Folder...</guimenuitem> +</menuchoice> +</term> +<listitem><para>Select a folder (or folders) to add to the +collection list. These folders will also be rescanned whenever +&juk; is started or +<menuchoice><guimenu>File</guimenu><guimenuitem>Reload</guimenuitem> +</menuchoice> is chosen.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Rename...</guimenuitem></menuchoice> +</term> +<listitem><para>Rename a playlist.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Duplicate...</guimenuitem></menuchoice> +</term> +<listitem><para>Create a duplicate of the selected playlist, and +prompt for a new name. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Reload</guimenuitem></menuchoice> +</term> +<listitem><para>Reloads the tag information on every file in the selected +playlist. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>Remove</guimenuitem></menuchoice></term> +<listitem><para>Remove the selected playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu><guimenuitem>Save</guimenuitem> +</menuchoice> +</term> +<listitem><para>Save the selected playlist.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu><guimenuitem>Save As...</guimenuitem> +</menuchoice> +</term> +<listitem><para>Save the selected playlist, with a different name.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="menu-edit"> +<title><guimenu>Edit</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Clear</guimenuitem> +</menuchoice> +</term> +<listitem><para>Removes the selected songs from the playlist.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="menu-view"> +<title><guimenu>View</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Show Search Bar</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle action that sets whether or not the +<link linkend="search-bar">Search Bar</link> is shown.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Show Tag Editor</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle action that sets whether or not the +<interface>Tag Editor</interface> is shown.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guimenuitem>Show History</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle action that sets whether or not the +<link linkend="juk-history-playlists">History Playlist</link> is shown.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu><guimenuitem>Default</guimenuitem> +</menuchoice> +</term> +<listitem><para>Switches to <link linkend="juk-viewmode-default">Default View mode</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu><guimenuitem>Compact</guimenuitem> +</menuchoice> +</term> +<listitem><para>Switches to <link linkend="juk-viewmode-compact">Compact View mode</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu><guimenuitem>Tree</guimenuitem> +</menuchoice> +</term> +<listitem><para>Switches to <link linkend="juk-viewmode-tree">Tree View mode</link>. +</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="menu-player"> +<title><guimenu>Player</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>Player</guimenu><guimenuitem>Random Play</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle option which controls the Random Play setting. +If Random Play is enabled, then &juk; will randomly select a random song from the +current playlist when the currently playing song is over.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Player</guimenu><guimenuitem>Loop Playlist</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle option which controls the Loop Playlist setting. +If Loop Playlist is enabled, then &juk; will start playing from the beginning when +it has finished playing every song in the current playlist.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Player</guimenu><guimenuitem>Play</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command starts playing the currently selected song, or resumes +playback of the song if it was paused.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Player</guimenu><guimenuitem>Pause</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command pauses the currently playing song. Use the +Play command to restart playback.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Player</guimenu><guimenuitem>Stop</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command stops the playback of the currently playing song. +You cannot resume playback from its current position after that.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Player</guimenu><guimenuitem>Previous Track</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command plays the song that was playing before +the currently playing song.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Player</guimenu><guimenuitem>Next Track</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command skips to the next song to play in the +playlist.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="menu-tagger"> +<title><guimenu>Tagger</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul"><keycap>Ctrl</keycap><keycap>T</keycap></keycombo></shortcut> +<guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command saves any changes to the tags that you are +editing. Normally, changes are not saved until you deselect the file you +are editing.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Tagger</guimenu><guimenuitem>Delete</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command deletes the currently selected files from +the Collection List and any playlists containing it, and then deletes +the selected file from the disk. +<!-- God this is a dumb place to put this particular command --></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul"><keycap>Ctrl</keycap><keycap>F</keycap></keycombo></shortcut> +<guimenu>Tagger</guimenu><guisubmenu>Guess Tag +Information</guisubmenu><guimenuitem>From Filename</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command tries to guess the tags of the selected files +by scanning the filename. You can configure the patterns used for guessing +by selecting <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Tag Guesser...</guimenuitem></menuchoice>, which opens the +<link linkend="juk-tag-guesser-configuration">Tag Guesser Configuration dialog</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul"><keycap>Ctrl</keycap><keycap>I</keycap></keycombo></shortcut> +<guimenu>Tagger</guimenu><guisubmenu>Guess Tag +Information</guisubmenu><guimenuitem>From Internet</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command tries to guess the tags of the selected files +by using the <application>trm</application> provided with +<ulink url="http://www.musicbrainz.org/">MusicBrainz</ulink>.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-settings"> +<title><guimenu>Settings</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guisubmenu>Toolbars</guisubmenu> +<guimenuitem>Show Main Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command shows or hide the <link linkend="main-toolbar">Main +Toolbar</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu><guisubmenu>Toolbars</guisubmenu> +<guimenuitem>Show Play Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command shows or hide the <link linkend="play-toolbar">Play +Toolbar</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Splash Screen on Startup</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle option. If enabled, &juk; will display +an informational screen upon startup as it loads your music collection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Dock in System Tray</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle option. If enabled, &juk; will display an +icon in your system tray. You can use the system +tray icon to tell if &juk; is playing, and control playback.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Stay in System Tray on Close</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle option. If enabled, &juk; will remain +running if you close the main window. The Dock in System Tray option must +also be enabled. To quit &juk;, use the <menuchoice><guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem></menuchoice> command from the main window, or +the <guimenuitem>Quit</guimenuitem> command from the system tray's context +menu.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Popup Track Announcement</guimenuitem> +</menuchoice> +</term> +<listitem><para>This is a toggle option. If enabled, &juk; will display +an indicator whenever a song starts playing, with information on the artist and +title, and with buttons allowing you to quickly switch to a different song. The +Dock in System Tray option must also be enabled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Tag Guesser...</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command brings up the <link linkend="juk-tag-guesser-configuration">Tag Guesser Configuration +dialog box</link>, where you can alter the patterns used to guess tag information +from filenames.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>File Renamer...</guimenuitem> +</menuchoice> +</term> +<listitem><para>This command brings up the <link linkend="juk-rename-dialog">File Renamer Configuration +dialog box</link>, where you can alter the way &juk; renames files for you.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem><para>This brings up the standard &kde; dialog box where you can configure +keyboard shortcuts for &juk;. Some reasonable defaults are included as well, including +Multimedia keys for people who have multimedia keyboards.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="keybindings"> +<title>Keybinding Reference</title> + +<!-- +ctrl-a select all +ctrl-c copy +ctrl-r rename file +ctrl-i guess tag entries from internet +ctrl-f guess tag entries based on filename +ctrl-f new search playlist +ctrl-n new empty playlist +ctrl-d new playlist from folder +ctrl-o open file (add to the collection or a playlist) +ctrl-q quit +ctrl-s save +ctrl-t save edited tag information +ctrl-v paste +ctrl-x cut +f1 Show manual +shift-f1 what's this help + +--> +<informaltable> +<tgroup cols="2"> +<thead> +<row> +<entry>Key Combination</entry> +<entry>Action</entry> +</row> +</thead> +<tbody> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>A</keycap></keycombo></entry> +<entry>Select all</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></entry> +<entry>Copy</entry> +</row> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>R</keycap></keycombo></entry> +<entry>Rename file</entry> +</row> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>I</keycap></keycombo></entry> +<entry>Guess tags from the Internet.</entry> +</row> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>G</keycap></keycombo></entry> +<entry>Guess tags from the filename.</entry> +</row> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>F</keycap></keycombo></entry> +<entry>New <link linkend="juk-search-playlists">search playlist</link>.</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></entry> +<entry>Guess tag entries based on filename</entry> +</row> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry> +<entry>New empty Playlist</entry> +</row> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>D</keycap></keycombo></entry> +<entry>New playlist from folder.</entry> +</row> +<row> +<entry><keycombo +action="simul">&Ctrl;<keycap>T</keycap></keycombo></entry> +<entry>Save changes to edited tags.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</sect1> +</chapter> + +<chapter id="credits-and-licenses"> +<title>Credits and Licenses</title> + +<para>&juk; Copyright © 2002, 2003, 2004 &Scott.Wheeler;.</para> + +<para>&juk; is developed and maintained by &Scott.Wheeler; +&Scott.Wheeler.mail;.</para> + +<para>Many thanks to the following people who have contributed to &juk;:</para> + +<itemizedlist> +<listitem><para>&Daniel.Molkentin; &Daniel.Molkentin.mail; for system tray docking, <quote>inline</quote> tag +editing, bug fixes, evangelism, moral support.</para> +</listitem> +<listitem><para>Tim Jansen <email>tim@tjansen.de</email> for +the <application>GStreamer</application> port</para> +</listitem> + +<listitem><para>Stefan Asserhäll <email>stefan.asserhall@telia.com</email> +for global shortcut support.</para> +</listitem> + +<listitem><para>Stephen Douglas <email>stephen_douglas@yahoo.com</email> +for track announcement popups.</para> +</listitem> + +<listitem><para>&Frerich.Raabe; &Frerich.Raabe.mail; +for automagical track data guessing, and bugfixes.</para> +</listitem> + +<listitem><para>Zack Rusin <email>zack@kde.org</email> +for more automagical things, including MusicBrainz support.</para> +</listitem> + +<listitem><para>Adam Treat <email>manyoso@yahoo.com</email> +for co-conspiring in MusicBrainz wizardry.</para> +</listitem> + +<listitem><para>Matthias Kretz <email>kretz@kde.org</email> +for being the friendly neighborhood &arts; guru.</para> +</listitem> + +<listitem><para>Maks Orlovich <email>maksim@kde.org</email> +for making &juk; friendlier to people with terabytes of music.</para> +</listitem> + +<listitem><para>Antonio Larrosa Jimenez <email>larrosa@kde.org</email> +for the &DCOP; interface.</para> +</listitem> + +</itemizedlist> + +<para>Documentation Copyright © 2003, &Lauri.Watts;, and copyright +© 2004 Michael Pyne.</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +&documentation.index; + +</book> +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: +--> diff --git a/doc/juk/juk-adv-search.png b/doc/juk/juk-adv-search.png Binary files differnew file mode 100644 index 00000000..240ffa10 --- /dev/null +++ b/doc/juk/juk-adv-search.png diff --git a/doc/juk/juk-file-renamer.png b/doc/juk/juk-file-renamer.png Binary files differnew file mode 100644 index 00000000..bc2bd702 --- /dev/null +++ b/doc/juk/juk-file-renamer.png diff --git a/doc/juk/juk-main.png b/doc/juk/juk-main.png Binary files differnew file mode 100644 index 00000000..b4bb08eb --- /dev/null +++ b/doc/juk/juk-main.png diff --git a/doc/juk/juk-tag-guesser.png b/doc/juk/juk-tag-guesser.png Binary files differnew file mode 100644 index 00000000..aa0a81ee --- /dev/null +++ b/doc/juk/juk-tag-guesser.png diff --git a/doc/juk/normal-playlist.png b/doc/juk/normal-playlist.png Binary files differnew file mode 100644 index 00000000..21725a72 --- /dev/null +++ b/doc/juk/normal-playlist.png diff --git a/doc/juk/search-playlist.png b/doc/juk/search-playlist.png Binary files differnew file mode 100644 index 00000000..e9453eae --- /dev/null +++ b/doc/juk/search-playlist.png diff --git a/doc/juk/toolbar.png b/doc/juk/toolbar.png Binary files differnew file mode 100644 index 00000000..cb656b23 --- /dev/null +++ b/doc/juk/toolbar.png diff --git a/doc/kaboodle/Makefile.am b/doc/kaboodle/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kaboodle/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kaboodle/index.docbook b/doc/kaboodle/index.docbook new file mode 100644 index 00000000..6df20400 --- /dev/null +++ b/doc/kaboodle/index.docbook @@ -0,0 +1,78 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "<application>kaboodle</application>"> + <!ENTITY package "kdemultimedia"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kappname; Handbook</title> + +<authorgroup> +<author> +<firstname></firstname> +<othername></othername> +<surname></surname> +<affiliation> +<address><email></email></address> +</affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Date and version information of the documentation +Don't forget to include this last date and this last revision number, we +need them for translation coordination ! +Please respect the format of the date (YYYY-MM-DD) and of the version +(Major.minor.lesser), it could be used by automation scripts --> + +<date>2000-09-02</date> +<releaseinfo>0.00.00</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&kaboodle; is a one file quick media player for &kde; +</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>Kapp</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> <title>Introduction</title> <para>Sorry, but +the documentation for &kappname; was not finished when &kde; was installed on +this computer.</para> <para>If you need help, please check <ulink +url="http://www.kde.org">The &kde; Website</ulink> for updates, or by +submitting your question to <ulink url="mailto:kde@kde.org">The +&kde; User Mailing list</ulink>.</para> <para><emphasis>The &kde; +Team</emphasis></para> + +&underFDL; + +</chapter> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +// vim:ts=2:sw=2:tw=78:noet +--> diff --git a/doc/kaudiocreator/Makefile.am b/doc/kaudiocreator/Makefile.am new file mode 100644 index 00000000..31d09cd4 --- /dev/null +++ b/doc/kaudiocreator/Makefile.am @@ -0,0 +1,2 @@ +KDE_DOCS = kaudiocreator +KDE_LANG = en diff --git a/doc/kaudiocreator/cdconfiguration.png b/doc/kaudiocreator/cdconfiguration.png Binary files differnew file mode 100644 index 00000000..9ef499a9 --- /dev/null +++ b/doc/kaudiocreator/cdconfiguration.png diff --git a/doc/kaudiocreator/cddbconfigurationlookup.png b/doc/kaudiocreator/cddbconfigurationlookup.png Binary files differnew file mode 100644 index 00000000..38d2e56c --- /dev/null +++ b/doc/kaudiocreator/cddbconfigurationlookup.png diff --git a/doc/kaudiocreator/cddbconfigurationsubmit.png b/doc/kaudiocreator/cddbconfigurationsubmit.png Binary files differnew file mode 100644 index 00000000..0b12bde3 --- /dev/null +++ b/doc/kaudiocreator/cddbconfigurationsubmit.png diff --git a/doc/kaudiocreator/cdinserted.png b/doc/kaudiocreator/cdinserted.png Binary files differnew file mode 100644 index 00000000..c6d5120b --- /dev/null +++ b/doc/kaudiocreator/cdinserted.png diff --git a/doc/kaudiocreator/confirmartistcarryover.png b/doc/kaudiocreator/confirmartistcarryover.png Binary files differnew file mode 100644 index 00000000..84eb1922 --- /dev/null +++ b/doc/kaudiocreator/confirmartistcarryover.png diff --git a/doc/kaudiocreator/encoderconfiguration.png b/doc/kaudiocreator/encoderconfiguration.png Binary files differnew file mode 100644 index 00000000..cfb685ab --- /dev/null +++ b/doc/kaudiocreator/encoderconfiguration.png diff --git a/doc/kaudiocreator/encodernotfound.png b/doc/kaudiocreator/encodernotfound.png Binary files differnew file mode 100644 index 00000000..6714ea9e --- /dev/null +++ b/doc/kaudiocreator/encodernotfound.png diff --git a/doc/kaudiocreator/entersong1.png b/doc/kaudiocreator/entersong1.png Binary files differnew file mode 100644 index 00000000..f92f21b8 --- /dev/null +++ b/doc/kaudiocreator/entersong1.png diff --git a/doc/kaudiocreator/generalconfiguration.png b/doc/kaudiocreator/generalconfiguration.png Binary files differnew file mode 100644 index 00000000..8d6c6b36 --- /dev/null +++ b/doc/kaudiocreator/generalconfiguration.png diff --git a/doc/kaudiocreator/index.docbook b/doc/kaudiocreator/index.docbook new file mode 100644 index 00000000..8cfe57e5 --- /dev/null +++ b/doc/kaudiocreator/index.docbook @@ -0,0 +1,1083 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kaudiocreator "<application>kaudiocreator 1.12</application>"> + <!ENTITY kappname "&kaudiocreator;"><!-- Do *not* replace kappname--> + <!ENTITY package "kdemultimedia"><!-- kdebase, kdeadmin, etc --> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kaudiocreator; Handbook</title> + +<authorgroup> +<author> +<surname>alan</surname> +<affiliation> +<address><email>sorry@no.mail</email>no mail, sorry.</address> +</affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>1999</year> +<year>2007</year> +<holder>alan</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Date and version information of the documentation +Don't forget to include this last date and this last revision number, we +need them for translation coordination ! +Please respect the format of the date (YYYY-MM-DD) and of the version +(V.MM.LL), it could be used by automation scripts. +Do NOT change these in the translation. --> + +<date>2007-01-15</date> +<releaseinfo>1.13</releaseinfo> + +<abstract> +<para> +&kaudiocreator; is an audio &CD; ripper for &kde;. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kaudiocreator</keyword> +<keyword>CD</keyword> +<keyword>ripper</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kaudiocreator; is an audio &CD; ripper for &kde;. With it you can easily rip your audio &CD;s to mp3 or ogg files or other formats, depending on whatever encoder you have installed on your system.</para> + +<para>&kaudiocreator; is a frontend to cdparanoia (vor ripping the &CD; data to wav files on your hard disk) and many encoders which encode (compress) these wav files. Currently lame for mp3, oggenc for oggs and flac (lossless compression) are supported out of the box (you may still need to install these encoder packages from your distro). But you can add more encoders with the program (if you have them installed).</para> + +<para>In general ripping an audio &CD; is a 2 step process: + <itemizedlist> + <listitem><para>first the &CD; tracks/songs are ripped to the computer into wav files (lossless, uncompressed) and then</para></listitem> + <listitem><para>in a second step these wav files (usually one per song) are compressed into mp3 or ogg format or other formats like the lossless flac.</para></listitem> + </itemizedlist> +</para> + +<para>For the 1st step, the ripping of the &CD;, &kaudiocreator; uses cdparanoia. Nearly every distro has a pre-compiled package, so install it, if you haven't done so already.</para> + +<para>For the 2nd step you need lame (for mp3), oggvorbis (for ogg) or other encoders to be installed. All these programs are usually provided for whatever linux distribution you may have, so it is most likely not necessary to compile anything yourself. You just might need to install any of these packages. You only have to install the encoder package you want to need. If you for instance don't need flac, there is no need to install it.</para> + +<para>What encoder/file format to use? The <link linkend="what_encoder">What encoder</link> chapter gives you a small introduction about encoders, audio quality and compression factors.</para> + +<para>One word to copy protected audio &CD;s: As already said, &kaudiocreator; uses cdparanoia to rip the audio data from the &CD;. This program is not designed to crack any copy protection. So unless your &CD;/DVD-player firmware circumvents the protection, you will fail to rip protected audio &CD;s. In any case &kaudiocreator; itself cannot handle/work around any protection mechanism. Your bad, just don't buy copy protected audio &CD;s and the market power will dry out this idiocy!</para> + +<para>Hey, still reading? Even if you just punched the help menu entry after opening the program the first time, not having a clue how to proceed from this somewhat empty screen (especially when no audio &CD; is already in the drive when starting the program) and the unusual short menu?</para> + +<para>Don't worry, this handbook will tell you how to rip a &CD; with this program. Beside the usual explanation of the programs commands/settings, there is a special section with a <link linkend="Example">full walkthrough example</link>. At first you will learn how to set the general settings. This includes your &CD; drive (device ID) the folder for temporary files, the main destination folder, in which a subfolder named according your choice from the &CD; parametes will be created for each &CD;, the encoder to use (like lame for mp3s or oggvorbis for oggs) and among other settings whether you want to use freedb to fetch the data for your &CD; from the Internet or (paranoia, not cdparanoia :-) ) whether you want to enter all data manually.</para> +<para>While the setup has only to be done once (you can however tweak it as often as you like until you find a suitable setup for yourself), you will then learn the daily business of ripping a &CD; to the harddrive. It is (hopefully) then when you will understand and learn to like the lean approach of the interface you may have stumbled over at first.</para> + +<para>Last remark, &kaudiocreator; is a very flexible program which can invoke many encoders. Therefore this handbook (currently) does not cover every possible command and setting. Use it as a starting point to explore the program yourself if you feel the need for more than what is covered here. Usually more information about the programs/encoders (app-name) which are called by &kaudiocreator; can be obtained by opening a console and typing <command>man app-name</command>, <command>app-name -help</command>, <command>app-name --help</command> or <command>app-name -h</command>.</para> + +<para>And now: Have fun...</para> +</chapter> + +<chapter id="using-kaudiocreator"> +<title>Using &kaudiocreator;</title> + +<para> +What are we talking about? Well you read this, so you have most likely started the program already. It should look somehow like this: +</para> +<para> + +<screenshot> +<screeninfo>Here's a screenshot of &kaudiocreator;</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="kaudiocreatormainwindow800.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; main window</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> +<para> +The main window after starting the program. +</para> + +<sect1 id="kaudiocreator-features"> +<title>A short list of &kaudiocreator; features</title> + +<itemizedlist> + <listitem><para>can encode to many formats - depends on what programs/encoders you have installed (mp3, ogg, flac &etc;)</para></listitem> + <listitem><para>can fetch &CD; information from freedb via the Internet or you can work completely off line, entering everything manually</para></listitem> + <listitem><para>can add tags to the created files - depends on what format you encode to</para></listitem> + <listitem><para>set folder names and song names according free adjustable combinations of &CD; information</para></listitem> +</itemizedlist> + +</sect1> +</chapter> + +<chapter id="commands"> +<title>Command Reference</title> + +<para>This is just a brief list of the commands of the main window. See the <link linkend="Example">full walkthrough example</link> for more details how to use this program and screenshots with descriptions about the program configuration tabs.</para> + +<sect1 id="kaudiocreator-mainwindow"> +<title>The main &kaudiocreator; window</title> + +<sect2> +<title>The <guimenu>File</guimenu> Menu</title> +<para> +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Eject CD</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the drive bay and ejects the &CD;.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>CDDB Lookup</guimenuitem> +</menuchoice></term> +<listitem><para><action>Starts the CDDB lookup of the cd data according your settings from the <guilabel>Lookup</guilabel> tab on the <guilabel>CDDB</guilabel> page. (Can be local or online, in the later case you have to connect to the Internet first.)</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Edit Album...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the Album Editor window.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Select All Tracks</guimenuitem> +</menuchoice></term> +<listitem><para><action>Selects all tracks for processing (ripping and, if set up, encoding).</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Deselect All Tracks</guimenuitem> +</menuchoice></term> +<listitem><para><action>Deselects all tracks for processing.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Rip Selection</guimenuitem> +</menuchoice></term> +<listitem><para><action>Starts the ripping and, if an encoder is selected on the <guilabel>Encoder Configuration</guilabel> tab in the settings dialog, the encoding.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guisubmenu>Rip Selection</guisubmenu> +</menuchoice></term> +<listitem><para><action>Opens a sub-menu with a list of the available encoders, so you can rip a selection with another encoder than the standard one. Note, that the encoder should have been configured on the <guilabel>Encoder Configuration</guilabel> tab in the settings dialog.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Remove Completed Jobs</guimenuitem> +</menuchoice></term> +<listitem><para><action>Remove the completed jobs from the <guilabel>Jobs</guilabel> window.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Encode File...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens a file browser so you can select an already ripped file to encode rather then rip and encode a complete &CD;.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Quits &kaudiocreator;.</action></para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +<sect2> +<title>The <guimenu>Settings</guimenu> Menu</title> +<para> +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Hide/Show Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para><action>Toggles the toolbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Hide/Show Statusbar</guimenuitem> +</menuchoice></term> +<listitem><para><action>Toggles the statusbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the configuration window to set shortcuts (key codes) to menu commands.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the configuration window to configure the toolbar.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Notifications...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens the configuration window to configure the type of notification (like logs, beeps) for program events (like finished &CD; ripping).</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &kaudiocreator;...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens &kaudiocreator; main configuration dialog with several tabs (like Encoder, for the encoder configuration). You have to go here before you will be able to succesfully use this program!</action></para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +<sect2> +<title>The <guimenu>Help</guimenu> Menu</title> + +&help.menu.documentation; + +</sect2> + +</sect1> +</chapter> + +<chapter id="what_encoder"> +<title>What encoder/file format to use - about audio quality, encoders and compression rates</title> + +<para>What encoder to use?</para> + +<para>If you don't want to loose any audio information you need a lossless audio format. Beside flac there are others like shorten or monkey, which may be available for your distro. The down side is that the compression rates will be low and hardly any commercial device can play these files.</para> + +<para>Between the audio formats which do lose information due to data compression according their psychoacustic model, mp3 and ogg are the most common. ogg may today have a slight advantage over mp3 in audio quality on lower bit rates (up to 128 kbps), but above that rate the differences become less important, as both encoders produce very good audio quality.</para> + +<para>In short:</para> + +<para>flac + <itemizedlist> + <listitem><para>+ lossless compression</para></listitem> + <listitem><para>+ free</para></listitem> + <listitem><para>+ very good audio quality (lossless)</para></listitem> + <listitem><para>- low compression rate (probably only around 2.x)</para></listitem> + <listitem><para>- hardware player support not existing (afaik)</para></listitem> + </itemizedlist> +</para> + +<para>ogg + <itemizedlist> + <listitem><para>- loss of audio information (amount depends on final bit rate)</para></listitem> + <listitem><para>+ free</para></listitem> + <listitem><para>+ good to very good (high bit rates) audio quality</para></listitem> + <listitem><para>+ high compression rate (depending on resulting audio quality)</para></listitem> + <listitem><para>- poor hardware player support</para></listitem> + </itemizedlist> +</para> + +<para>mp3 + <itemizedlist> + <listitem><para>- loss of audio information (amount depends on final bit rate)</para></listitem> + <listitem><para>o 'not so' free, lame comes for free with most distros but there are license issues</para></listitem> + <listitem><para>+ good to very good (high bit rates) audio quality, though slightly lower at lower bit rates compared to ogg</para></listitem> + <listitem><para>+ high compression rate (depending on resulting audio quality)</para></listitem> + <listitem><para>+ good hardware player support</para></listitem> + </itemizedlist> +</para> + +<para>As mentioned before, mp3 and ogg both are audio formats with which you will lose sound information in the end. You cannot revert back to the original once you have the mp3/ogg files. You can create wav files of these and even burn them back onto a &CD; to play them on a &CD;-Player (while DVD-players usually can play both, wav and mp3, mostly not ogg) but the wav files generated from a mp3 or ogg will not be as good as the original. In reality, depending on your HiFi system and the compression rate you chose when creating the mp3s/oggs, you might not even hear a difference. However, if you do not want to lose any sound information but still want to compress your wave files, you should take a look into flac, shorten or monkey. But these encoders will not compress much better than the factor of 2.x .</para> + +<para>Until you are not the absolute enthusiast you will most likely decide between ogg and mp3. Go for</para> + +<para>ogg - if you want to listening to the music only via your computer or a computer based music server and/or you already have one of the few ogg playing players.</para> + +<para>mp3 - if you want to listen to your music on other devices as well, like standard DVD players, portable players (USB stick, flash card, HD) or special car stereos. Today, early 2005, most of these devices only support the mp3 format.</para> + +<para>Qualitywise both audio formats should be just fine, depending the compression rate you choose. For mp3 (and most likely ogg too) a bit rate of 128 kbps results in a compression rate of 11 compared to the original wav file which is stored on the &CD;. That might be good during travel but is not sufficient for a good home HiFi stereo system. 192 kbps is a good compromise even for you HiFi system in your living room. This would give you a compression rate of 7.3 .</para> + +<para>Already years ago experts were not able to differentiate a 256 kbps mp3 from the &CD; original and that was in a blind test with a HiFi system which you might never be able to affort. :-) That still will reduce the storage space of the original wav by the factor of 5.5 , quite nice. On most modern systems you can as well use variable bit rate. Here the encoder varies the bit rate depending the complexity of the music according to its psychoacoustic model (wow :-) ). The lame setting '--preset extreme' generates a file with a VBR (variable bit rate in opposite to CBR, constant bit rate) of 224 to 256 kbps, depending the complexity of the music. This will compress the original by a factor up to 6.3 and will play on nearly everything currently on the market.</para> + +<para>Unless you have an extremly expensive equipment (we are talking of thousands of Euros or US Dollars) and an extremly well trained ear, you will most likely not hear a difference to the maximum possible CBR rate of 320 kbps, just beleave me. Even that would still result in a compression rate of 4.4 . By the way, the setting '--preset extreme' will infact use 320 kbps for complex music parts while compressing less complex music much higher to achieve the average bit rate of 224 to 256 kbps.</para> + +<para>A short list of audio quality parameters and resulting compression rates for lame (mp3s) (check lame --help for more): + <itemizedlist> + <listitem><para>'--preset extreme' = 224 to 256 kbps VBR, compression rate up to 6.3 . Uses up to 320 kbps for complex music parts and way less for less complex parts of the song. Good enough for high quality home HiFi systems. First choice!</para></listitem> + <listitem><para>'--preset extreme -b 256 = 256 kbps CBR, compression rate around 5.5 . Uses always 256 kbps for complex and not so complex music parts of the song. Some older players need CBRs. Good enough for high quality home HiFi systems.</para></listitem> + <listitem><para>'-h' = 128 kbps CBR joint stereo, compression rate about 11 . 128 kbps for all parts of the song. Good enough for kids music, portable players and, well, car stereos. Not good enough for better home Hifi systems, though.</para></listitem> + </itemizedlist> +</para> + +</chapter> + + +<chapter id="parameters"> +<title>&CD; info parameters</title> + +<para>The &CD; information you enter or the program fetches automatically from freedb via the Internet, is available as a list of parameters within the program which can be parsed to/used with &kaudiocreator; and the encorder programs in order to create folder and file names and or generate tags in the song files.</para> + +<para>When used with encoder programs, often you have to use a combination of program switches from the encoder program and these parameters here. The manual or help of the encoders will tell you the switches for these programs.</para> + +<para>E. g. to add the &CD; title to a tag when encoding mp3s with lame you have to add the -tt switch from lame followed by the title parameter from &kaudiocreator;. The result looks then like '... -tt {title} ...' .</para> + +<para>This is a summary of the parameters from &kaudiocreator; you can use (= button name in the wizard):</para> +<itemizedlist> + <listitem><para>%{albumartist} - album artist (Artist)</para></listitem> + <listitem><para>%{albumtitle} - album title (Album)</para></listitem> + <listitem><para>%{artist} - song artist (Track Artist)</para></listitem> + <listitem><para>%{albumcomment} - album comment (Comment)</para></listitem> + <listitem><para>%{comment} - song comment (Track Comment)</para></listitem> + <listitem><para>%{extension} - file extension like mp3 or ogg (Extension)</para></listitem> + <listitem><para>%{genre} - music genre (Genre)</para></listitem> + <listitem><para>%{title} - song title of current track (Track Title)</para></listitem> + <listitem><para>%{number} - number of current track (Track Number)</para></listitem> + <listitem><para>%{~} - standard linux shortcut for the users home folder (Home Folder)</para></listitem> +</itemizedlist> + +</chapter> + + +<chapter id="freedb"> +<title>freedb - what's that?</title> + +<para> +You are not alone with your wish to listen to your music independently of your audio &CD;. People all over the world are ripping their &CD;s and converting it into a different format. Everybody makes the same experience: The most time consuming part in this process is the input of the &CD; data. So some smart people had the idea, that it would be much more efficient, if only one person would do this for every &CD; and the rest could just fetch the &CD; data and save the typing work.</para> + +<para>That's what freedb is, a free database where audio &CD; rippers can input/upload the infos of a &CD; so that everybody else can download this information rather than typing it into the computer each by themselfs. Note, we are only talking text here: &CD; title, artist, song names &etc;, not the audio file itself.</para> + +<para>So is it legal and save to use?</para> + +<para>Yes, it should be legal, but I am not a lawyer. However, nobody can prevent you from issuing the &CD; information which is openly available on the &CD; anyhow. And better, without the the &CD; the info is more or less pointless, so no damage can be done to the artists or the audio companies. You can obtain all the information anyhow by strolling through a &CD; shop, physically or online.</para> + +<para>Save to use? Well, for retrieving the &CD; information, you do not need to reveal any personal data yourself. There are freedb mirrors in many countries and you can even download the database to work off-line. (Be warned, now in early 2005 it is already a 370 MB tar.bz2 file!). You are asked to setup a mail address to fetch data, but this can be a faked one. I would actually recommend this, to ensure that your mail address is not accidentally be slipped to public and you are ending up getting lot's of spam mail. The initiator of the service claim they will not track or store your data (so why asking for it anyhow??) and then, many mirrors are in the hands of trusted institutions.</para> + +<para>In &kaudiocreator; you have to actively check a box to enable smtp (sending of an address) and you can specify a different (faked) address to use with freedb other than the one the system is set up with. The way the configuration is designed, it seems, that the email address is not used when retrieving data from the server. (But I am not the programmer, haven't checked the code.)</para> + +<para>However, to be able to give feedback the initiators of freedb ask that in case you submit data (about a new, not yet listed &CD; or a correction of an existing entry) you should do so with a valid email address. It's a great service, so respect this wish in case you want to and have something to contribute! There shouldn't be anything to worry beside the fact that your mail address might fall into the wrong hands and you receive (more) spam. (You may just not want to use your 'best' address). Please read carefully the corresponding FAQ and How-To's at freedb.org if you think you have a &CD; which data has not yet been submitted to the database.</para> + +<para>There are mirrors of the master database in many countries. When you set up &kaudiocreator; to use freedb, please use the mirror nearest to you. This saves bandwith on the net and balances the load between the servers.</para> + +<para>Visit freedb.org to get an up-to-date list of mirrors for online retrieval of &CD; information every time you rip a &CD; or to download the full database or (usually monthly created) updates of the database.</para> + +<para>Oh, how does it work?</para> + +<para>Well due to some magic a (not so) unique ID is automatically generated from the &CD; data when it is entered/present in the drive. That might be the number of tracks and their length and/or other things. See freedb.org for more information. Funny enough but unfortunately, the created ID does not seem to be unique for each &CD;. So sometimes a &CD; has to be sorted into a wrong category, out of the 11 defined by freedb, because there is already a &CD; with the same key in the database for the correct category. For backward compatibility they don't want to change the key generation. However, that should be only exceptional. :-) Check freedb.org for the categories before submitting. For instance the category rock holds pop and rap &CD;s as well, as there does not exist a category pop or rap.</para> + +</chapter> + + +<chapter id="faq"> +<title>Questions and Answers</title> + +&reporting.bugs; +&updating.documentation; + +<qandaset id="faqlist"> +<qandaentry> +<question> +<para>What ripper (program) is used to extract the songs from the &CD; into wav files on my computer?</para> +</question> +<answer> +<para>Well, I haven't scanned the source but rumor has it, that cdparanoia is used for that. That has always been the best choice for ripping audio &CD;s. Note, that you have to install the cdparanoia package from your distro, if it isn't already.</para> +<para>Meanwhile cdda2wav has cought up and there might be areas, like mixed mode &CD;s, where it has surpassed cdparanoia. For simple &CD; ripping cdda2wav uses now the same library as cdparanoia. However, this info is of not much use for you as you cannot change the &CD; ripper in &kaudiocreator;. In case you have problems ripping a &CD; and you want to try cdda2wav you have to use another program like grip, a ripper using gtk and which let's you define the ripper program you want to use.</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>What encoders/file formats are supported? Can I create mp3 or ogg files?</para> +</question> +<answer> +<para>You can choose the encoder and therefore the file format you want to turn the ripped wav files into. On first opening you will find pre-defined entries for lame (mp3s), oggenc (oggs) and flac (a lossless compression audio format) on the encoder setup tab. But you can add other encoders on that tab as well.</para> +<para>Note, that you have to install the encoder package from your distro for the encoder you want to use first, before you can use the encoder. (That's required even for the pre-defined encoders!). Take a look at the <link linkend="what_encoder">What encoder</link> chapter for more information about encoders.</para> +<para>After installation of an encoder you can get more information about its switches by typing something like <command>lame -help</command> or <command>lame --help</command> in a console (⪚ konsole). While 'lame' has to be replaced by the name of the encoder you installed.</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>There isn't much working here, is it?</para> +</question> +<answer> +<para>Ha, a thousand possible reasons for that. Check the &CD;/DVD drive device ID setting, access/read permission and whether you have installed cdparanoia and the audio encoder of your choise (lame for mp3s, oggenc for oggs, flac &etc;). Try invoking both programs from a command line in a terminal. That might give you a hint what's wrong.</para> +<para>Oh, by any chance, you don't try to rip a copy protected audio &CD;, do you? Check the cover of the &CD;. This won't work! Your bad, buy unprotected audio &CD;s next time.</para> +<para>There is a chapter with a <link linkend="Example">full walkthrough example</link>. Even if you want to use different settings it might give you a hint how to proceed.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> + + +<chapter id="Example"> + +<title>Example from a first start over the basic setup to the first rip of a &CD;</title> + +<para>Read the complete handbook, understood everthing and somehow still unsure what to do? Well, no problem, follow this step by step example and you will get enough information to adjust just those areas which will the program make do exactly what you want.</para> + +<para>In this example we will start the program for the first time, set everything up and rip our first &CD;. We will use lame '--preset extreme' to create mp3s with a VBR (Variable Bit Rate) of 224 to 256 kbps in average and ID3V1 tags.</para> + +<para>You need to have cdparanoia and lame installed on your system. Both programs should be available as a pre-compiled package for your linux distribution. However, you might need to ask a search engine to find a suitable package of lame, as sometimes it is considered to be not totally free. In any case you might not need to compile from source which, of course, you always can.</para> + +<para>The structure how we organize our music on the hard disk is: + <itemizedlist> + <listitem><para>main dir name for all &CD;s : /usr/share/cd</para></listitem> + <listitem><para>in that for each &CD; a subdir named : cdartist - cdtitle - year</para></listitem> + <listitem><para>in the subdir the song names : track# - tracktitle</para></listitem> + </itemizedlist> +</para> +<para>In summary : /usr/share/cd/cdartist - cdtitle - year/track# - tracktitle</para> +<para>Please make sure, that the folder <filename>/usr/share/cd</filename> exists and that you have write permission on it (⪚ try to copy something to it with konqueror).</para> + +<para>The example is divided into 2 sections: + <itemizedlist> + <listitem><para>the first covering the basic setup of &kaudiocreator;, something you might only do once and</para></listitem> + <listitem><para>the second describing the process of actually ripping a &CD;, which you will have to repeat for every &CD; you rip.</para></listitem> + </itemizedlist> +</para> + +<para>Here we go...</para> + +<sect1 id="Basic-Setup"> + <title>E 1 Basic Setup</title> + + <para>Here we set the encoder to use to compress the music (lame) and so the audio file format (mp3) as well as the resulting audio quality (--preset extreme => VBR 224 to 256 kbps). You define where the files will go and what structure will be used to store them. In set the program to use freedb to get the &CD; data via Internet as we are lazy.</para> + + <para>While you can always change any of these settings, you will most likely don't change them every time you rip a &CD; once you found a convenient setup.</para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.1 Step 01: Setting the device ID for your &CD;/DVD drive/writer</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>On the main window:</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="kaudiocreatormainwindow800.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; main window</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>set <guilabel>Device:</guilabel> to <filename>/dev/cdrom</filename></para> + <para>The device ID is parsed to the ripper program so it can read the &CD; data/songs.</para> + <para>Often /dev/cdrom is a symlink to the actual device ID from your drive. If that does not work or you have more than one &CD;/DVD drive, you can give the exact device ID. If you can access your drive with other programs, take a look into /etc/fstab and try the device entries for &CD-ROM; and or DVD-drives listed there.</para> + <para>Nothing in there, no luck?</para> + <para>Running kernel 2.6:</para> + <para>If you happen to have one of the common &ATAPI; (or IDE) drives, with kernel 2.6 the device ID will range from /dev/hda to /dev/hdd. The master on channel 2 is a good starting point: that would be /dev/hdc. If your hard disks are all S-ATA, /dev/hda will probably do the trick. Native SCSI drives will start from /dev/sda unless you have S-ATA hard disks, which come first in the list, so depending on the number of disks the &CD;/DVD drive will start at /dev/sdb or /dev/sdc .</para> + <para>Running kernel 2.4:</para> + <para>&CD;/DVD drives are accessed via SCSI, so the devices start at /dev/sda .</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.2 Step 02: General Configuration Tab</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Settings -> Configure KAudioCreator... -> General</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="generalconfiguration.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; General Configuration Tab</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para> + The <guilabel>General Configuration</guilabel> tab. Not much to do here. You could define some additional formating though. For our example, just enter/leave everything as shown in the screenshot. + </para> + <para>Just check <guilabel>Prompt if information is not complete</guilabel>, so you will get informed when some infos for generating tags are not available.</para></listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.3 Step 03: CD Configuration Tab</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Settings -> Configure KAudioCreator... -> &CD;</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="cdconfiguration.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; &CD; Configuration Tab</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>The <guilabel>&CD; Configuration</guilabel> tab. Just check both entries. We are lazy and want that the &CD; data is fetched automatically via the Internet from a freedb server.</para> + <para>Note, you need to be online when ripping the &CD; to be able to access the freedb server.</para> + <para>The second box is convenient, as if a &CD; entry is found, the &CD; will be ripped imidiately. That's low risk, because if you are later unhappy with the database entry and the resulting director/file names or tag entries, you can easily change them. The folder and file names with konqueror->rename and the id3 tags with kid3, the &kde; tagger.</para> + <para>Further note appart from this example: If you want to enter everything manually uncheck the boxes and freedb will not be used. You can use freedb locally in off-line mode if you download the database before. However, this will be over 370 MB so think twice if it's worth it. To use freedb in off-line mode, you need to check the boxes here, at least the first one. The mode is set on the following tab.</para></listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.4 Step 04: CDDB Configuration Lookup Tab</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Settings -> Configure KAudioCreator... -> CDDB -> Lookup tab</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="cddbconfigurationlookup.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; CDDB Configuration Lookup Tab</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>CDDB, that's freedb for us. The settings used for the data lookup, for retrieving the &CD; information from the freedb server via the Internet. How does the system know what data to get? Read <link linkend="freedb">the section about freedb</link>. Just set everything as in the screenshot.</para> + <para>Short explanation:</para> + <para>Mode: We haven't downloaded the database, so we want to work remote with the Internet server only.</para> + <para>CDDB Server: PLEASE (yes, I am shouting!) go to freedb.org and look up a mirror near you. This way the load is balanced between the mirror servers. However, as a first try, this setting should work, but PLEASE...</para> + <para>Port and Transport: There are 2 combinations, which even the mirrors should understand.</para> + <itemizedlist> + <listitem><para>Port=80 and Transport=&HTTP;</para></listitem> + <listitem><para>Port=8880 and Transport=CDDB</para></listitem> + </itemizedlist> + <para>Both work equally regarding the server, but as many firewalls blocking Port 8880 by default, you may have better luck with Port 80, as the &HTTP; port is usually open for browsing the Internet.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.5 Step 05: CDDB Configuration Submit Tab</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Settings -> Configure KAudioCreator... -> CDDB -> Submit tab</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="cddbconfigurationsubmit.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; CDDB Configuration Submit Tab</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>In this example we don't want to submit any &CD; data to the freedb server. Uncheck the first box and that should it be.</para> + <para>Note beside this example: If one day you find a &CD; which is not yet known by the freedb server or you find an error in a &CD; entry, you can submit the new/updated data. Check the first box at the top of this tab and then either use your mail address known to your system which &kaudiocreator; has already detected or check the lower radio button and enter a new mail address. Please read <link linkend="freedb">the section about freedb</link> first. You are asked to provide a mail address when submitting new or updated entries to the server and you should read the information on freedb.org about revision counts when sending updated information in case you found an error.</para></listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.6 Step 06: Ripper Configuration Tab</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Settings -> Configure &kaudiocreator;... -> Ripper</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="ripperconfiguration.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Ripper Configuration Tab</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>Just take the settings from the screenshot. (Make sure the folder <filename>/tmp</filename> exists on your system!)</para> + <para><guilabel>Beep after each rip is done</guilabel> : check this to get an audible feedback from the progress.</para> + <para><guilabel>Number of tracks to rip at a time</guilabel> : sorry, cannot think of a reason to do more than one with one drive? Reading and encoding parallel? Just don't know, try for yourself.</para> + <para><guilabel>Auto-eject &CD; after last track is ripped</guilabel> : yeah well, so you know it's done. Do what you like.</para> + <para><guilabel>Default Temporary Directory</guilabel> : If you check this, you can/must specify the path/folder where the wav files are ripped into. This might be handy if you only have space on another drive. If not checked the files will be created in your home folder. Remember this path if you want do something with the wav files themselfs.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.7 Step 07: Encoder Configuration Tab</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Settings -> Configure KAudioCreator... -> Encoder</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="encoderconfiguration.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Encoder Configuration Tab</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>Finally the encoder configuration. We will use lame. Here we have a little bit more to do:</para> + <para>Click on <guilabel>Lame</guilabel></para> + <para>Click on the <guibutton>Configure...</guibutton> button</para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="lameconfiguration.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Lame Configuration</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>Uff, enter everything as in the screenshot. The command entry is a bit long, so you may have to scroll a bit to the right.</para> + <para>The settings are more or less self explaining. There is a space between '--preset' and 'extreme' .</para> + <para>'--preset extreme' defines the audio quality of the mp3s. As mentioned before, this is a setting for very good audio quality, sufficient even for very good HiFi Stereo systems. The resulting bit rate is about 224 to 256 kbps in average. The achieved compression factor is 6.3 . A good balance between audio quality and space consumption. Storage space/memory is cheap these days, isn't it?</para> + <para>Note the '--id3v1-only' entry to limit the tag creation to V1/V1.1 tags. Delete it if you want id3v2 tags as well. kid3 is a very good id3 tagger for &kde; in case you want to manipulate tags later. %f and %o should be the internal variables for the input file (incl. the full path) and the output file name (incl. the full path).</para> + <para>Click <guibutton>OK</guibutton> to close and apply the settings.</para> + <para><guilabel>Encoded File Location</guilabel> - Back on the <guilabel>Encoder Configuration</guilabel> tab, we define here the destination folder including the folder name for the files from the ripped &CD;. These are variables which will be filled with the corresponding &CD; data everytime you rip a &CD;. The &CD; data can be entered manually or fetched via Internet (CDDB). As already configured in this example, we will use freedb and fetch the data automatically. Play with the Wizard, but in the end for this example the entry should be:</para> + <para>'/usr/share/cd/%{albumartist} - %{albumtitle} - %{year}/%{number} - %{title}.%{extension}'</para> + <para>Set the rest as in the screenshot. A few comments for future use outside this example:</para> + <para><guilabel>'Number of wav files to encode at a time</guilabel>: Why would one want to encode more than one wav file at the time, multi-processor machines? Well, these will come soon, so if you already have one when you read this, give it a try.</para> + <para><guilabel>Encoder Priority</guilabel>: for the fanatics, :-) , play with it, if you feel for it. Higher is faster I guess!</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para>That's about it, we have just finished the basic setup of KAudioCreator. This configuration is used as the default for every &CD; rip. If you have choosen your music organization structure wise you will never have to change it again. ;-)</para> + +</sect1> + +<sect1 id="Ripping-a-CD"> + <title>E 2 Ripping a &CD;</title> + + <para>Ready to rumble! This section will describe the process of ripping a &CD; onto the harddrive. We will create mp3 files. The folder structure, the way the music is organised on the hard disk, was described and setup in the previous section. So connect to the Internet now, as we are lazy and want to fetch the &CD; data from freedb! The process described in this section has to be repeated for ever &CD; you want to rip.</para> + <para>As we use a &CD;, which is not already listed in freedb, the screenshots might look a bit different as the ones you will encounter for a &CD; which could successfully fetched from freedb. Therefore you will learn to enter the &CD; data manually rather than fetching it from the Internet but comments will be made to point out the differences.</para> + <para>Don't try too hard to look for the &CD; we use in this example. It's a 'special' handbook-writer edition. ;-) Sadly these days, you never know...</para> + <para>Here we go...</para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 2.1 Step 01: Ripping a CD.</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>The main window with an audio &CD; in the drive:</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="cdinserted.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; main window - cd inserted</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>If you haven't done so far, insert the &CD; into the drive which device ID you specified here on this main window.</para> + <para>After a short moment the tracks and their length should be listed on the window, as in the screenshot. That is, if the &CD; could be identified as an audio &CD; and read by cdparanoia.</para> + <para>If that's not happening, check the <link linkend="faq">Questions and Answers</link> section for help or go back to the previous section covering the basic setup.</para> + <para>Attention: if the &CD; could successfully fetched from freedb, all song titles will already be filled out and above the track list, the artist and album name will be shown.</para> + <para>In case that there are more than one entry in the database which matches the 'unique' &CD; key for your &CD;, a popup window will appear and you can select the database entry which you think fits best for your &CD;.</para> + <para>If you have not checked the box for automatically querying freedb (<guilabel>&CD; Configuration</guilabel> page in the settings dialog), you can trigger this manually with the first button from the button bar. If you don't have a local database but fetching from the Internet you need to be connected to the net.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 1.2 Step 02: The Album Editor - Enter the album data and the first song title</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Double click anywhere in the first, blue 'highlighted' row (track 1):</action> + </para> + <para>The Album Editor window pops up.</para> + <para> + <screenshot> + <mediaobject> + <imageobject><imagedata fileref="startalbumeditor.png" format="PNG"/></imageobject> + <textobject><phrase>Screenshot &kaudiocreator; The Album Editor</phrase></textobject> + </mediaobject> + </screenshot> + </para> + <para>Enter the album data for your &CD; according the pattern in the next screenshot. The song title in the Track 1 row of the Current Track box, the rest of the &CD; data in the Album box.</para> + <para>No need to enter the artist in the Current Track box, unless of course, you have a sampler with different artists for each song.</para> + <para>The upper comment field can be used for individual comments for each song, where as the Album comment field can be used for comments which should be the same across all songs.</para> + <para>Attention: of course, when you have successfully fetched the data from freedb the Album Editor is not empty but already holds the data as shown in the following screenshot. However, it is always a good idea to open the Album Editor once to check whether you are happy not only with the artist and album name (e.g. all words start with capital letters or not...) but to check if there are any unwanted comments.</para> + <para> + <screenshot> + <mediaobject> + <imageobject><imagedata fileref="entersong1.png" format="PNG"/></imageobject> + <textobject><phrase>Screenshot &kaudiocreator; enter title for song 1 and album data</phrase></textobject> + </mediaobject> + </screenshot> + </para> + <para>Note: In this example we are using only id3v1 tags. This limits the length of the fields to 30 characters for the artist, album and song title and only 28 characters for the comment field. If you want to create id3v2 tags, you can use unlimited field length, well, at least what &kaudiocreator; allows here. Haven't checked. You set this option on the encoder configuration tab, take a look into the Basic Setup section for this.</para> + <para>You can change the tag information of the created files later at any time with a tag editor. Kid3 is a good one for mp3 files with which you can create id3v2 tags, too.</para> + <para>Tags may not be supported by all encoder/file formats. Check the encoder help for more information about this.</para> + + <para>After clicking <guibutton>OK</guibutton> a confirmation message pops up:</para> + <para> + <screenshot> + <mediaobject> + <imageobject><imagedata fileref="confirmartistcarryover.png" format="PNG"/></imageobject> + <textobject><phrase>Screenshot &kaudiocreator; Confirm album data change carry over</phrase></textobject> + </mediaobject> + </screenshot> + </para> + <para>We changed the general album data and so a message pops up, asking whether we want to take over this change for the other songs. Yep, we do. Will save us some work. Click Yes.</para> + <para>Attention: this popup window will not appear, if you for instance change the album name in the Album box. However, the change will be valid for the other songs as well.</para> + + <para>And another pop-up window:</para> + <para> + <screenshot> + <mediaobject> + <imageobject><imagedata fileref="setalbumcategory.png" format="PNG"/></imageobject> + <textobject><phrase>Screenshot &kaudiocreator; Set album category</phrase></textobject> + </mediaobject> + </screenshot> + </para> + <para>We are asked to select a music category for the album. Don't mix this up with the genre for the id3 tags. These are the 11 categories which are defined by freedb to pre-sort the &CD; IDs. As our &CD; is not in any database (how could it the way we use the program), we have to choose one so in case we would submit the &CD; data, it would be sorted correctly into the freedb database.</para> + <para>Just choose one of the entries which seems to match the style of the &CD; you rip. It's not important for this example, we don't submit the &CD; data anyways. For more info go to freedb.org and read about the categories. Pop or Rap for instance are listed under Rock.</para> + <para>After hitting OK, you come back to the main window again. Just double click on the row of the second track.</para> + <para>Again the Album Editor window pops up and you can see, that the Album box is already filled out with the data we entered for the first track. So just enter the field entries in the Current Track box. The song title for sure and other information if you want.</para> + <para>Click into the next row on the main screen and proceed this way until you entered the track data for all tracks on the &CD;.</para> + <para>Attention: this popup will not show up, if you have fetched the data from freedb. It was already sorted into one of these categories in the database.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 2.3 Step 03: Start ripping</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Hit the <guibutton>Rip Selection</guibutton> button as shown on the screenshot</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="readytorip.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Start the ripping process</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>It's the 3rd button on the toolbar. Note, that the artist and album is shown above the track list.</para> + <para>Further note, that there is a check sign in front of every track row. Only the tracks which are marked that way will be processed. A single click on the track row will toggle the track selection. Ensure, that all tracks are selected or use the button <guibutton>Select All Tracks</guibutton> at the bottom of the screen (not shown on screenshot) to select all tracks at once.</para> + + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="jobshavestarted.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Message jobs have started</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>Once you have started the ripping process by clicking on the <guibutton>Rip Selection</guibutton> button, this confirmation window pops up. Hit OK and then we will take a look at the jobs window to follow what's going on.</para> + + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <variablelist> + <varlistentry> + <term> + <menuchoice> + <guimenuitem>E 2.4 Step 04: Following the progress on the jobs window</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + <action>Hit the <guilabel>Jobs</guilabel> tab to switch to the jobs window. It's on the upper left of the screen, right under the toolbar with the buttons.</action> + </para> + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="jobcontrol.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Job control window</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>That's the job control window. The first track is just ripped to the hard disk. A program status is shown on the lower left screen in the status row.</para> + + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="encodernotfound.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Encoder not found</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>Aarrrrgh! Sh*t ! Suddenly this. RTFM (read the f***ing manual)! I wrote it! Why, I am incapable! That's what you'll see, when you try to encode with/invoke an encoder which you haven't installed yet. Tracks that could not successfully encoded will get marked with a red 'x' on the job list, too.</para> + <para>By the way, see how I cheated? The path for the tmp file and the destination path is not what we set up here in the example. Shame over me, but you have checked that you have write access to both, the folder for the temporary files and the destination folder, haven't you? ;-)</para> + <para>Let's do that again...</para> + + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="rippingandencoding.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Ripping and encoding</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>Hm, now it becomes clear, why the error occured just after the rip of the first song was finished.</para> + <para>See that? Job one, ripping the first track, is gone (finished) but we have a new entry: Job 4 which is the encoding of track 1 to mp3. So ripping and encoding is done parallel. See the status message on the bottom of the window, it's enhanced now.</para> + <para>I could not find a configuration setting to suppress this behavior. The only thing that seems to be configurable is the number of parallel rips and encodings. Wow, do even more jobs parallel? I don't know, what this means on lower end machines? The AMD64 used here didn't seem to have a problem ripping and encoding a track (two different though) at once.</para> + + <para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="rippingandencoding2.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot &kaudiocreator; Ripping and encoding 2</phrase> + </textobject> + </mediaobject> + </screenshot> + </para> + <para>Well, the cycling goes on. Now we are ripping the last track while encoding another one and having one in the encoder queue. After the last track is encoded, a small pop up message is shown on the upper left of the window for a short time.</para> + <para>That's it, ready for the next &CD;. Enjoy listening to your music...</para> + </listitem> + </varlistentry> + </variablelist> + </para> + +</sect1> + +</chapter> + + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kaudiocreator; +</para> +<para> +Program copyright 2003-2007 Benjamin Meyer <email>ben+kaudiocreator@meyerhome.net</email> +</para> +<para> +Contributors: +<itemizedlist> + <listitem><para>A one man show so far!<email>nope@no.mail</email></para></listitem> +</itemizedlist> +</para> + +<para> +Documentation copyright 2005-2007 alan <email>sorry@no.mail</email> +</para> +<para> +As a bad example: sorry no mail. I cannot maintain this handbook. It is thought as a first starter for a handbook for kaudiocreator. Whoever may think of something useful to add or change, may do so. Well, at least after contacting the author first, I assume. And if you read this, he left this section in and therefore agrees to this proposal. +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> +&underGPL; <!-- GPL License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kaudiocreator"> +<title>How to obtain &kaudiocreator;</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>In order to successfully use &kaudiocreator;, you need &kde; 3.x. and cdparanoia. If you want to create compressed audio files like mp3s or oggs, you need the encoder of your choice.</para> + +<para> +&kaudiocreator; is today maintained within the &kde; CVS as part of the kdemultimedia package. If you are familier with cvs you can do an anonymous checkout from there. However, most distros come with a pre-compiled package, especially because &kaudiocreator; is part of a main &kde; package. Install the kdemultimedia package from your distro. If you read this, you have most likely found it already... +</para> + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +<para>Funny, if you managed to checkout the source from the &kde; SVN you won't need this info here but...</para> + +&install.compile.documentation; + +</sect1> + +<sect1 id="configuration"> +<title>Configuration</title> + +<para>Well, this section is most likely intended for people who build from source and not the user using a pre-compiled package from a distro.</para> + +<para>Sorry, there is currently no help available for configuration options before compiling the source.</para> + +<para>If you look for help to configure the program to your needs once it is running, then the following is for you:</para> + +<para>Being a program that can invoke many different other programs there is a lot to configure. Best read the <link linkend="Example">full walkthrough example</link> to introduce yourself with the configuration options. It sports screenshots of the different configuration tabs and provides comments even for options not used in the example.</para> + +</sect1> + +</appendix> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +--> + diff --git a/doc/kaudiocreator/jobcontrol.png b/doc/kaudiocreator/jobcontrol.png Binary files differnew file mode 100644 index 00000000..de89ac26 --- /dev/null +++ b/doc/kaudiocreator/jobcontrol.png diff --git a/doc/kaudiocreator/jobshavestarted.png b/doc/kaudiocreator/jobshavestarted.png Binary files differnew file mode 100644 index 00000000..a4d306ab --- /dev/null +++ b/doc/kaudiocreator/jobshavestarted.png diff --git a/doc/kaudiocreator/kaudiocreatormainwindow800.png b/doc/kaudiocreator/kaudiocreatormainwindow800.png Binary files differnew file mode 100644 index 00000000..46751313 --- /dev/null +++ b/doc/kaudiocreator/kaudiocreatormainwindow800.png diff --git a/doc/kaudiocreator/lameconfiguration.png b/doc/kaudiocreator/lameconfiguration.png Binary files differnew file mode 100644 index 00000000..8fbc0710 --- /dev/null +++ b/doc/kaudiocreator/lameconfiguration.png diff --git a/doc/kaudiocreator/readytorip.png b/doc/kaudiocreator/readytorip.png Binary files differnew file mode 100644 index 00000000..2ebead2e --- /dev/null +++ b/doc/kaudiocreator/readytorip.png diff --git a/doc/kaudiocreator/ripperconfiguration.png b/doc/kaudiocreator/ripperconfiguration.png Binary files differnew file mode 100644 index 00000000..1269eb47 --- /dev/null +++ b/doc/kaudiocreator/ripperconfiguration.png diff --git a/doc/kaudiocreator/rippingandencoding.png b/doc/kaudiocreator/rippingandencoding.png Binary files differnew file mode 100644 index 00000000..d15703a5 --- /dev/null +++ b/doc/kaudiocreator/rippingandencoding.png diff --git a/doc/kaudiocreator/rippingandencoding2.png b/doc/kaudiocreator/rippingandencoding2.png Binary files differnew file mode 100644 index 00000000..dcd3a42a --- /dev/null +++ b/doc/kaudiocreator/rippingandencoding2.png diff --git a/doc/kaudiocreator/setalbumcategory.png b/doc/kaudiocreator/setalbumcategory.png Binary files differnew file mode 100644 index 00000000..8562dade --- /dev/null +++ b/doc/kaudiocreator/setalbumcategory.png diff --git a/doc/kaudiocreator/startalbumeditor.png b/doc/kaudiocreator/startalbumeditor.png Binary files differnew file mode 100644 index 00000000..e1052ddc --- /dev/null +++ b/doc/kaudiocreator/startalbumeditor.png diff --git a/doc/kioslave/Makefile.am b/doc/kioslave/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kioslave/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kioslave/audiocd.docbook b/doc/kioslave/audiocd.docbook new file mode 100644 index 00000000..982e1f23 --- /dev/null +++ b/doc/kioslave/audiocd.docbook @@ -0,0 +1,208 @@ +<article lang="&language;" id="audiocd"> +<title>audiocd</title> +<articleinfo> +<authorgroup> +<author>&Rik.Hemsley; &Rik.Hemsley.mail;</author> +<author><personname><firstname>Benjamin</firstname><surname>Meyer</surname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2004-09-16</date> +<releaseinfo>2.30.00</releaseinfo> + +</articleinfo> + +<para>Allows treating audio <acronym>CD</acronym>s like a +<quote>real</quote> filesystem, where tracks are represented as files +and, when copied from the folder, are digitally extracted from the +<acronym>CD</acronym>. This ensures a perfect copy of the audio +data.</para> + +<para>To see how this slave works, insert an audio <acronym>CD</acronym> +in your &CD-ROM; drive and type <userinput>audiocd:/</userinput> into +&konqueror;. Within a few seconds you should see a list of tracks and +some folders.</para> + +<para>Audio <acronym>CD</acronym>s don't really have folders, but +the audiocd slave provides them as a convenience. If you look inside +these folders you will see that they all contain the same number of +tracks. If you are connected to the Internet, some folders will have +the actual track titles shown as the filenames.</para> + +<para>The reason that these separate folders exist are so that you +can choose in which format you would like to listen to (or copy) the +tracks on the <acronym>CD</acronym>.</para> + +<para>If you drag a track from the <filename class="directory">Ogg +Vorbis</filename> folder and drop it on another &konqueror; window +open at your home folder, you should see a progress window showing +you that the track is being extracted from the <acronym>CD</acronym> and +saved to a file. Note that Ogg Vorbis is a compressed format, so the +file in your home folder will appear a great deal smaller than it +would have been if you had copied the raw data.</para> + +<para>The mechanism behind this is quite simple. When the audiocd slave +is asked to retrieve a track from the <filename class="directory">Ogg +Vorbis</filename> folder, it starts extracting the digital audio data +from the <acronym>CD</acronym>. As it sends the data over to the file in +your home folder, it simultaneously encodes it in Ogg Vorbis format +(<acronym>CD</acronym> audio is in an uncompressed format to start +with).</para> + +<para>You could also try dragging a file ending in <literal +role="extension">.wav</literal> and dropping it on the &kde; Media +Player, &noatun;. In this case, the procedure that happens behind the +scenes is similar, except that instead of encoding the audio data in Ogg +Vorbis format, it is put through a very simple conversion, from raw +binary data (which the <literal role="extension">.cda</literal> files in +the toplevel folder represent) to <quote>RIFF WAV</quote> format, a +non-compressed format that most media players understand.</para> + +<para>&noatun; should quite happily play the <literal +role="extension">.wav</literal> file, but if it has trouble, you may +consider using the <option>paranoia_level</option> option, explained +below.</para> + +<variablelist> +<title>Options</title> + +<varlistentry> +<term><option>device</option></term> +<listitem> +<para>Set the path to the audio <acronym>CD</acronym> device, ⪚ +<userinput>audiocd:/<option>?device</option>=<parameter>/dev/sdc</parameter></userinput>. +Normally, the slave will try to find a <acronym>CD</acronym> drive with +an audio <acronym>CD</acronym> inserted, but if it fails or you have +more than one <acronym>CD</acronym> drive, you may want to try this +option. Note that the configuration dialog allows you to set a default +value for this option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>fileNameTemplate</option></term> +<listitem> +<para>Set the file name template, ⪚ +<userinput>audiocd:/<option>?fileNameTemplate</option>=<parameter>Track %{number}</parameter></userinput>. Note that the configuration dialog allows you to set a default value for this option. A warning that if you set it to an empty string no files will show up.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>albumNameTemplate</option></term> +<listitem> +<para>Set the album name template, ⪚ +<userinput>audiocd:/<option>?albumNameTemplate</option>=<parameter>%{albumartist} %{albumtitle}</parameter></userinput>. Note that the configuration dialog allows you to set a default value for this option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>niceLevel</option></term> +<listitem> +<para>Sets the process nice level for encoders, ⪚ +<userinput>audiocd:/<option>?albumNameTemplate</option>=<parameter>niceLevel=10</parameter></userinput>. Note that the configuration dialog allows you to set a default value for this option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>paranoia_level</option></term> +<listitem> +<para>Set the amount of error detection and correction used when +extracting data.</para> + +<variablelist> +<varlistentry> +<term>Level 0</term> +<listitem> +<para>No detection or correction. Only useful if you have a perfect +<acronym>CD</acronym> drive (unlikely).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Level 1</term> +<listitem> +<para>Enable basic error checking and correction.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Level 2</term> +<listitem> +<para>Default. Specifies that only a perfect extraction will be +accepted.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Note that there is a disadvantage to level 2. Extraction can be +very slow, so real-time digital playback may not work properly. If you +have a good quality <acronym>CD</acronym> drive (note that more +expensive does not necessarily mean better quality) then you probably +won't experience very slow extraction, but a poor drive may take days +(!) to extract the audio from one <acronym>CD</acronym>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>cddbChoice</option></term> +<listitem> + +<para>Specify which Internet <acronym>CD</acronym> Database entry to use. Audio +<acronym>CD</acronym>s don't have track names, but the Internet +<acronym>CD</acronym> Database is a clever system which uses a special +unique identifier generated from the number and length of tracks on each +<acronym>CD</acronym> to cross-reference a track listing. Track listings +are contributed by the Internet community and made available to +all. Occasionally there will be multiple entries. You can specify which one to use.</para> + +<para>You can submit your own track listings using &kscd;, the &kde; +<acronym>CD</acronym> player.</para> + +<para>By default audiocd tries to pick the best one.</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>Examples</title> +<varlistentry> +<term><userinput>audiocd:/?device=/dev/scd0&paranoia_level=0&cddbChoice=0</userinput></term> +<listitem> +<para>Gives a listing of the tracks on the audio <acronym>CD</acronym> +inserted in <filename class="devicefile">/dev/scd0</filename>, which on +&Linux; specifies the first <acronym>SCSI</acronym> &CD-ROM; device. If +you copy tracks from the <acronym>CD</acronym>, digital extraction will +be performed without error correction or detection. The +<acronym>CDDB</acronym> Database entry 0 will be used.</para> +</listitem> +</varlistentry> +</variablelist> + +<qandaset> +<title>Frequently Asked Question</title> +<qandaentry> +<question> +<para>I get <errorname>The file or folder / does not +exist</errorname>. How do I fix that? I have an audio +<acronym>CD</acronym> in my drive!</para> +</question> + +<answer> +<para>Try running <userinput><command>cdparanoia</command> +<option>-vsQ</option></userinput> as yourself (not <systemitem +class="username">root</systemitem>). Do you see a track list? If not, +make sure you have permission to access the <acronym>CD</acronym> +device. If you're using <acronym>SCSI</acronym> emulation (possible if +you have an <acronym>IDE</acronym> <acronym>CD</acronym> writer) then +make sure you check that you have read and write permissions on the +generic <acronym>SCSI</acronym> device, which is probably <filename +class="devicefile">/dev/sg0</filename>, <filename +class="devicefile">/dev/sg1</filename>, &etc;. If it still doesn't work, +try typing <userinput>audiocd:/?device=/dev/sg0</userinput> (or similar) +to tell kio_audiocd which device your &CD-ROM; is.</para> +</answer> +</qandaentry> +</qandaset> + + +</article> diff --git a/doc/kmid/Makefile.am b/doc/kmid/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kmid/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kmid/index.docbook b/doc/kmid/index.docbook new file mode 100644 index 00000000..6670dd54 --- /dev/null +++ b/doc/kmid/index.docbook @@ -0,0 +1,1338 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kmid;"> + <!ENTITY package "kdemultimedia"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kmid; Handbook</title> +<authorgroup> +<author> +<firstname>Antonio</firstname> +<surname>Larrosa Jiménez</surname> +<affiliation> +<address><email>larrosa@kde.org</email></address> +</affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>1999</year><year>2001</year> +<holder>Antonio Larrosa Jiménez</holder> +</copyright> + +<date>2002-02-05</date> +<releaseinfo>2.00.00</releaseinfo> + +<abstract> +<para> +&kmid; is a midi/karaoke multimedia player +</para> +</abstract> + +<keywordset> +<keyword>KMid</keyword> +<keyword>midi</keyword> +<keyword>karaoke</keyword> +<keyword>multimedia</keyword> +<keyword>mid</keyword> +<keyword>kar</keyword> +<keyword>player</keyword> +<keyword>music</keyword> +<keyword>sound</keyword> +<keyword>fm</keyword> +<keyword>awe</keyword> +<keyword>gus</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&kmid; is &kde;'s midi and karaoke multimedia player. It features some +features not found in any other &UNIX; midi player, such as realtime +graphics and karaoke text highlighting among others. +</para> + +<para> +&kmid; has been reported to run on &Linux; and FreeBSD operating +systems. It uses the <acronym>OSS</acronym> sound driver, so it should +run on every system where &kde; and <acronym>OSS</acronym> +compile. &kmid; also supports the &Linux; Ultrasound Project Driver , +which is required to get sound in <acronym>GUS</acronym> cards. I plan +to support the <acronym>ALSA</acronym> driver as soon as it supports a +sequencer device. +</para> + +<para> +&kmid; shows the lyrics in the screen changing its color at the same +time the music is playing, so it is very easy to follow the tune of the +songs. +</para> + +<para> +Hope you find &kmid; as fun to use as I found developing it. +</para> + +<para> +Antonio Larrosa Jiménez <email>larrosa@kde.org</email> +</para> + +<sect1 id="kmids-features"> +<title>&kmid;'s features</title> + +<para> +These are some of &kmid;'s main features: +</para> + +<itemizedlist> +<listitem> +<para> +It has a very <emphasis>friendly user interface</emphasis> to display karaoke +text with <emphasis>realtime highlighting</emphasis> of lyrics. +</para> +</listitem> +<listitem> +<para> +It features a graphical view of what is being played on each midi channel, by +highlighting the keys pressed in (virtual) keyboards. +</para> +</listitem> +<listitem> +<para> +The most powerful <emphasis>Midi Mapper</emphasis> that you will ever find in +any operating system. +</para> +</listitem> +<listitem> +<para> +<emphasis>Drag & drop</emphasis> so you can drop in &kde; any midi file from a +&konqueror; window. +</para> +</listitem> +<listitem> +<para> +You can <emphasis>change the tempo</emphasis> of songs to play them slower or +faster at your wish. +</para> +</listitem> +<listitem> +<para> +It shows lights to follow the rhythm of the song. +</para> +</listitem> +<listitem> +<para> +<emphasis>Customizable fonts</emphasis> for karaoke text to be displayed. +</para> +</listitem> +<listitem> +<para> +Supports the two standards to introduce lyrics in midi files, that is, lyrics or +text events (and guess which one a song uses automatically). +</para> +</listitem> +<listitem> +<para> +Session Management. If a song is playing while you logout from &kde;, the next +time you login, the same song will start playing. +</para> +</listitem> +<listitem> +<para> +<emphasis>Adjustable volume</emphasis> in realtime. +</para> +</listitem> +<listitem> +<para> +It can play broken midi files which make other players core dump! +</para> +</listitem> +<listitem> +<para> +It can open <emphasis>gzipped midi/karaoke files</emphasis> just as any other +file. +</para> +</listitem> +<listitem> +<para> +Consumes approximately <emphasis>0.1%</emphasis> of my +<acronym>CPU</acronym> (depends on the complexity of the song). +</para> +</listitem> +<listitem> +<para> +Supports external midi synths, <acronym>AWE</acronym>, <acronym>FM</acronym> and +<acronym>GUS</acronym> cards (for the latter you need the <acronym>LUP</acronym> +driver and gusd installed). +</para> +</listitem> +<listitem> +<para> +Runs on &Linux; and FreeBSD (maybe also other unices ...). +</para> +</listitem> +</itemizedlist> + +</sect1> +</chapter> + +<chapter id="general-usage"> +<title>General usage</title> + +<sect1 id="opening-songs"> +<title>Opening songs</title> + +<para> +You can open a song several different ways. +</para> + +<para> +First, you can select <guimenuitem>Open...</guimenuitem> from the +<guimenu>File</guimenu> menu, then you are presented with a standard +open dialog, with which you can select the song you wish to open. +</para> + +<para> +You can drag a file from a &konqueror; window and drop it in the &kmid; window. +You can also Drag & Drop multiple songs at the same time. +</para> + +<para> +If you specify a song in the command line when running &kmid;, it will also be +opened. +</para> + +<para> +And the final way is by selecting the song from the list of songs of the active +collection. +</para> + +</sect1> + +<sect1 id="playing-songs"> +<title>Playing songs</title> + +<para> +To play a song, first open it, and then press on the +<guiicon>Play</guiicon> button of the toolbar, choose the +<guimenuitem>Play</guimenuitem> entry of the <guimenu>Song</guimenu> +menu, or just press the <keycap>Space</keycap> key. +</para> + +<para> +Note that when you open a file using Drag & Drop, &kmid; will start +playing it automatically (if you drop more than one file, they will be +added to a collection and they will be played sequentially). +</para> + +<para> +Once &kmid; is playing a song, you can move the time slider, by pressing +with the &MMB; mouse button, to go to a specified position. +</para> + +<para> +If a song is playing too fast or too slow for you, you can press on the +arrows at both sides of the tempo <acronym>LCD</acronym> and make it +play faster or slower. To get back to the default tempo, just do a +double click on the tempo <acronym>LCD</acronym>. +</para> + +<para> +The <keycap>Space</keycap> key is used for two things, when music is +playing, and you press the <keycap>Space</keycap> key, it will act as +when you press on the <guiicon>pause</guiicon> button or the +<guimenuitem>Pause</guimenuitem> entry of the <guimenu>Song</guimenu> +menu, that is, it will pause music. If you press the +<keycap>Space</keycap> key when no music is being played, &kmid; will +play it. +</para> + +</sect1> + +<sect1 id="displaying-lyrics"> +<title>Displaying lyrics</title> + +<para> +There are two methods to store lyrics in a song, by using +<guimenuitem>Text events</guimenuitem> or <guimenuitem>Lyrics +events</guimenuitem>, some songs use the first, some the second, some +use both of them, and some don't include lyrics :-) +</para> + +<para> +&kmid; lets you choose which events to display, and even better, it has +an option to automatically select the type of events that a song uses, +so that you don't have to change the type manually . That way, if you +activate the <guimenuitem>Automatic Text Chooser</guimenuitem> entry of +the <guimenu>Settings</guimenu> menu, the karaoke text will be +automatically selected, but you can still change them if you prefer to +see the other type. +</para> + +<para> +To select which type to see, you can use the appropriate entries in the +<guimenu>Settings</guimenu> menu, or just press the <keycap>1</keycap> +and <keycap>2</keycap> keys of your keyboard to see the +<guimenuitem>Text events</guimenuitem> or <guimenuitem>Lyrics +events</guimenuitem> respectively. +</para> + +</sect1> + +</chapter> + +<chapter id="collections"> +<title>Collections</title> + +<para> +A collection is a list of midi files that you put in a set, and which +are played one after another. This section will help you to use them, +and will give you some useful tips to make a good use of them. +</para> + +<sect1 id="creating-a-collection"> +<title>Creating a collection</title> + +<para> +To create a collection, first open the <guilabel>Collections +Manager</guilabel> dialog, by selecting the <guimenuitem>Organize +...</guimenuitem> entry of the <guimenu>Collections</guimenu> menu . +Then click on the <guibutton>New</guibutton> button, and enter the name +you want the collection to have. +</para> + +<para> +You can also copy a complete collection by selecting it and then +pressing the <guibutton>Copy</guibutton> button, which will ask you for +the name of the new collection that will have initially the same songs +as the selected collection. +</para> + +<para> +Once you have more than one collection, you can change the active +collection from the <guilabel>Collections Manager</guilabel>, by +selecting it. +</para> + +</sect1> +<sect1 id="the-temporary-collection"> +<title>The Temporary Collection</title> + +<para> +The Temporary Collection is a collection that is used to hold songs you +want to play but that you don't want to add to any collection. +</para> + +<para> +This collection is <emphasis>not saved</emphasis> on exit of the +application, so keep it in mind when you add lots of songs to it. +</para> + +<para> +Keep on reading this section for a better understanding of the Temporary +Collection. +</para> + +</sect1> + +<sect1 id="adding-songs-to-a-collection"> +<title>Adding songs to a collection</title> +<subtitle>How to use <guimenuitem>AutoAdd to a +collection</guimenuitem></subtitle> + +<para> +There are some different ways to add a song to a collection. +</para> + +<para> +First of all in each method, you must have selected the collection you +want to add songs to in the <guilabel>Collections Manager</guilabel>. +Then you can press on the <guibutton>Add</guibutton> button to add a +song, there will appear an open file dialog so that you can choose which +song to add. +</para> + +<para> +The other methods to add a song depend on the state of the +<guimenuitem>AutoAdd to Collection</guimenuitem> option. +</para> + +<para> +If <guimenuitem>AutoAdd to Collection</guimenuitem> is enabled, when +you open a song (using <menuchoice><guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem></menuchoice> or Drag & Drop) it +(they) will be added to the active collection without user intervention. +</para> + +<para> +If <guimenuitem>AutoAdd to Collection</guimenuitem> is not enabled, +when you open a song the Temporary Collection will be activated and +cleared, and the opened songs will be added to it. +</para> + +</sect1> + +<sect1 id="removing-songs-from-collections"> +<title>Removing songs from collections</title> + +<para> +To delete a song from a collection, just open the <guilabel>Collection +Manager</guilabel>, select the appropriate collection, and the song you +wish to delete, and then click on the <guibutton>Remove</guibutton> +button. +</para> + +</sect1> + +<sect1 id="playing-order"> +<title>Playing in order or at random</title> + +<para> +You can select the order in which songs will be played . When you select +<guimenuitem>In order</guimenuitem> mode from the <guisubmenu>Play +Order</guisubmenu> submenu of the <guimenu>Collections</guimenu> menu, +songs will be played in the same order in which they were added to the +collection. +</para> + +<para> +When you select <guimenuitem>Shuffle</guimenuitem> mode, &kmid; will +generate a random variable with a discrete uniform distribution to +really play randomly the songs in the collection . It will give values +to that random variable while generating the list in which order the +songs will be played (you surely want to play random songs, but don't +want to play twice the same song, and you want to play the last played +song when you press on the <guibutton>Previous Song</guibutton> button, +don't you ? :-) ). +</para> + +<para> +The random list in which the collection will be played will be +regenerated each time you add or remove a file in the active collection, +and when you press on the <guimenuitem>Shuffle mode</guimenuitem> entry +of the menu. +</para> + +</sect1> + +<sect1 id="selecting-from-a-collection"> +<title>Selecting a song from a collection</title> + +<para> +You can select a song to play in the <literal>Collection +Manager</literal>, or by using the combo box over the karaoke text. +</para> + +<para> +You can also change to the next song by using the <literal>Next +Song</literal> entry of the <literal>Song</literal> menu, the +<literal>Next Song</literal> button of the toolbar, or pressing the +<literal>right arrow</literal> key. +</para> + +<para> +To change to the previous song, use the <guimenuitem>Previous +Song</guimenuitem> entry of the <guimenu>Song</guimenu> menu, the +<guimenuitem>Previous Song</guimenuitem> button of the toolbar, or press +the <keycap>left arrow</keycap> key of your keyboard. +</para> + +</sect1> + +<sect1 id="deleting-a-collection"> +<title>Deleting a collection</title> + +<para> +To delete a collection, simply open the <guilabel>Collection +Manager</guilabel>, select the collection you want to delete, and click +on <guibutton>Delete</guibutton>. Easy, it isn't? </para> + +<para> +Please keep in mind that you cannot delete the Temporary Collection, but +it doesn't matter as it is not saved when you quit &kmid;. +</para> + +</sect1> + +</chapter> + +<chapter id="midi-maps"> +<title>Midi Maps</title> + +<sect1 id="what-is-a-midimap"> +<title>What is a midi map ?</title> + +<para> +A Midi Map is something that maps midi events in other midi events. +</para> + +<para> +This is totally needed if a synthesizer doesn't understand the standard +events (that is, if a synthesizer is not General Midi compliant), in +this case, a midi map will translate General Midi events in the events +that that synthesizer understands. +</para> + +<para> +For example you can make a midi map that converts all the +<literal>Change patch to Bright Piano</literal> events, to +<literal>Change patch to Trumpet</literal> events, and so when a song +tries to play a piano, it will play a trumpet instead. +</para> + +<para> +This may sound odd, (why playing a trumpet when the song is made to play +a piano?), but it is very useful. The <acronym>GM</acronym> standard +specifies that when a midi keyboard receives an event to change patch to +<literal>0</literal>, it will change the current patch to <literal>Grand +Piano</literal>, but older synthesizer will change for example to a +<literal>Electric Guitar</literal> when it receives a +<literal>0</literal>. This old keyboard, needed to receive a +<literal>3</literal> (for example) to change to a +<literal>Piano</literal>. And here comes the midi map in action, +changing all <literal>change patch to 0</literal> to <literal>change +patch to 3</literal> and thus really playing the correct instrument when +it has to. +</para> + +</sect1> + +<sect1 id="do-i-need-a-midi-map"> +<title>Do I need a midi map ?</title> + +<para> +In short, if you don't have an external synth, <emphasis>no</emphasis>! +</para> + +<para> +If you only have a sound card, midi maps are not needed because all the +sound cards are <acronym>GM</acronym> compliant (this include AWE cards, +<acronym>GUS</acronym> cards, <acronym>FM</acronym> devices and so on). +</para> + +<para> +If you are playing music through an external synthesizer, and it is not +GM compliant, you will need to make a midi map for your midi keyboard . +Although you will perhaps be a whole afternoon doing your map file and +trying different values for all the options, you will be fully rewarded +when you finish it, because then you will find all the hidden +possibilities of your keyboard. For example, I have a low-cost Yamaha +PSS-790, which is not <acronym>GM</acronym> compatible, and doesn't has +as many instruments as a <acronym>GM</acronym> synthesizer, but with +&kmid;'s midi mapper, it sounds even better than many soundcards +(including AWE :-)), due to the sound quality found in external synths +(even on non <acronym>GM</acronym> compliant ones). +</para> + +</sect1> + +<sect1 id="creating-a-midi-map"> +<title>Creating a midi map</title> + +<para> +There isn't any program to generate midi maps, so you will have to edit a file +by hand (using your favorite text editor). +</para> + +<para> +A Midi map is a text file that keeps all the needed translations there will be +made when playing music. +</para> + +<para> +It consist of four sections: <literal>PATCHMAP</literal>, +<literal>KEYMAP</literal>, <literal>CHANNELMAP</literal> and +<literal>OPTIONS</literal>. +</para> + +<para> +Each section must appear only once, except the <literal>KEYMAP</literal> section +that can appear as many times as needed, provided that each appearance use a +different TextID (continue reading for details). +</para> + +<para> +The general structure of a map file is: +</para> + +<screen>DEFINE PATCHMAP +... +END + +DEFINE KEYMAP "Name of Keymap" +... +END + +DEFINE KEYMAP "Another Keymap" +... +END + +DEFINE CHANNELMAP +... +END + +OPTIONS +... +END +</screen> + +<para> +You can see that the <literal>DEFINE</literal> word is used to specify +which section is going to be started (except for +<literal>OPTIONS</literal>), and <literal>END</literal> is put at the +end of each section. </para> + +<para> +You can put comments by starting the line with a +<literal>#</literal> character. +</para> + +<para> +Please, don't forget to send me your map file by email, so that future +releases of &kmid; will include support for more non General Midi +compliant keyboards. +</para> + +<sect2 id="the-patchmap-section"> +<title>The <literal>PATCHMAP</literal> section</title> + +<para> +This section is used to specify how patches are going to be mapped, from +GM to your keyboard specs . The general usage is: +</para> + +<screen>(Name of GM Patch name)=(<replaceable>N</replaceable>) [AllKeysTo M] +</screen> + +<para> +Where <replaceable>N</replaceable> is the number that you keyboard needs to +receive to change the patch to the same that the GM standard does . +</para> + +<para> +Please note that the left side of the equal sign is ignored, so +<acronym>GM</acronym> patches are supposed to be in order (from 0 to 127) , and +so you are not allowed to change the order of the lines nor to omit any of the +128 instruments. +</para> + +<para> +The optional <literal>AllKeysTo M</literal> is used to map all notes +that use that instrument to the <literal>M</literal> key . For example, +suppose that your midi keyboard doesn't have a Gun Shot sound (GM patch +127) so you want to map it to a percussion drum (i.e. key 60), which +sounds similar to a gun shot, then you can put in the 127th line of the +<literal>PATCHMAP</literal> section: +</para> + +<screen>Gunshot =100 AllKeysTo 60</screen> + + +<para> +So when a midi file tries to play a note with the patch 127 (gun shot), it will +be mapped to the patch 100 (your keyboard's percussion patch) and play the note +60 (independently of the key that was going to be played). +</para> + +<para> +Please note that when I use the expression <quote>Percussion patch</quote>, I +mean the patch in which each key plays a different drum, cymbal, tom, maracas +and so on, and not to a possible sound which some keyboards have and which plays +a different tone of the same drum with each key. +</para> + +</sect2> + +<sect2 id="The-keymap-section"> +<title>The <literal>KEYMAP</literal> section</title> + +<para> +The <literal>KEYMAP</literal> section is used to specify how keys are +going to be mapped, within a given channel or instrument . The usage is: +</para> + +<screen>DEFINE KEYMAP "Name of Keymap" +C 0 =0 +C#0 =1 +D 0 =2 +... +END +</screen> + +<para> +As with the <literal>PATCHMAP</literal> section, it is very important +the order of the lines, and that they are all there (the 128 keys). +</para> + +<para> +As you can define multiple keymaps for different channels and instruments, +you must give a different name to each one in the first line. +</para> + +<para> +Keymaps are mainly used to map keys in the percussion channel . Have a +look at the distributed maps to see some examples. +</para> + +</sect2> + +<sect2 id="the-channelmap-section"> +<title>The <literal>CHANNELMAP</literal> section</title> + +<para> +This section can be used to map some channels to different ones . For +example, if you want to swap the first and second channels, you can +easily do it within the <literal>CHANNELMAP</literal> section. +</para> + +<para> +However it is more useful for keyboards that need the percussion +channel to be in a given channel (the GM standard use the channel 10, +others use the channel 16 and others use channel 9). +</para> + +<para> +Note that midi devices use 16 channels, so the <literal>CHANNELMAP</literal> +section, has 16 lines, from 0 to 15 , as this one: +</para> + +<screen>(N) = (M) [Keymap "Name"] [ForcePatch x] +</screen> + +<para> +Where <literal>N</literal> is the channel which is mapped to the +<literal>M</literal> channel . If the <literal>Keymap</literal> option +is used, the Keymap with name <literal>Name</literal> will be used in +this channel (this Keymap should be defined earlier in the map file !) . +If the <literal>ForcePatch</literal> option is used, all events that try +to change the patch which is used in this channel will be ignored, and +patch <literal>x</literal> will be used instead. +</para> + +<para> +The <literal>ForcePatch</literal> option may be useful for example to +always use the percussion patch on the percussion channel. +</para> + +</sect2> + +<sect2 id="the-options-section"> +<title>The <literal>OPTIONS</literal> section</title> + +<para> +The <literal>OPTIONS</literal> section has some general options that can +be very useful: +</para> + +<screen>OPTIONS +PitchBenderRatio = r +MapExpressionToVolumeEvents +END +</screen> + +<para> +You can specify both options, only one, or none of them. +</para> + +<para> +The <literal>PitchBenderRatio r</literal> value, has the ratio by which +pitch bender events will be multiplied . That is, when a midi file tries +to send a pitch bender event with a <literal>n</literal> value, the real +value that will be sent is <literal>n*(r/4096)</literal> (the +<literal>4096</literal> value is for not having to put decimal points in +the map file). +</para> + +<para> +This is used because the <acronym>GM</acronym> standard says that when a +midi keyboard receives a Pitch Bender event with a 4096 data value, it +should bend the note to a higher one , but some midi keyboards try to +bend the initial note by two or more higher notes (even an octave +higher!) when they receive a 4096 . This can be easily fixed by trying +different values so that instead of sending a 4096, KMid sends the +appropriate value. +</para> + +<para> +When the <literal>MapExpressionToVolumeEvents</literal> option is set in +the map file, and a midi file try to send an expression event, KMid will +send a volume event which is understood by more non-GM keyboards, and +which has a similar effect . There are many midi files which use +expression events to fade out at the end of a song, so if you feel that +music should be heard softer and softer, you can turn on this option and +see if this is what you need, because your midi synthesizer could be +ignoring the expression events because it doesn't understand them. +</para> + +</sect2> + +</sect1> + +<sect1 id="using-midimaps"> +<title>Using midi maps</title> + +<para> +To use a midi map, simply open the <guilabel>Midi Setup</guilabel> +dialog by selecting the <guimenuitem>Midi Setup ...</guimenuitem> entry +of the <guimenu>Settings</guimenu> menu. +</para> + +<para> +Then click on <guilabel>Browse ...</guilabel>, select the map file within the open +file dialog and enjoy the music ! :-) +</para> +</sect1> +</chapter> + +<chapter id="advanced-features"> +<title>Advanced features</title> + +<sect1 id="the-channel-view"> +<title>The Channel View</title> + +<para> +The Channel view is a window where you are shown a heap of keyboards (one for +each midi channel). In these keyboards, the notes that are being played with +each instrument are highlighted so that you can see what is each instrument +playing. +</para> + +<sect2 id="changing-instruments"> +<title>Changing instruments</title> + +<para> +You can use the Channel View to change the instrument that each channel is +playing. In each channel there is a combo box where you can select it. Once you +change it, the green button next to it will change to red to indicate that this +is not the default instrument. +</para> + +<para> +If you want to set again the default instrument, click on the red button, and it +will be automatically set. +</para> + +</sect2> + +<sect2 id="changing-the-look"> +<title>Changing the look mode</title> + +<para> +The Channel View has two different ways (for now) to display the played notes, +you can select them from the <guimenuitem>Channel View Options...</guimenuitem> +item in the <guimenu>Settings</guimenu> menu. +</para> + +<para> +You can choose between a mode in which played keys are pressed, as if it were a +normal piano (<guilabel>3D look</guilabel>), or a mode in which keys are also +filled with red color, so that pressed keys are easily recognized (<guilabel>3D +- filled</guilabel>). If you play the piano, or any other music instrument, you +can use this view to learn to play a song by yourself. I've used this technique +and it (along with a tempo reduction) is great to +learn new compositions. +</para> + +</sect2> + +</sect1> + +<sect1 id="the-tempo-lcd"> +<title>The Tempo <acronym>LCD</acronym></title> + +<para> +This shows the tempo in which a song is played, that is, the velocity of the +song. The higher this number is, the faster the song will play. +</para> + +<para> +You can also change the tempo of the song, so if a song plays too fast for you +to follow the lyrics, you can make it play slower. To change the tempo, you can +use the arrows that appear at each sides of the <acronym>LCD</acronym>. +</para> + +<para> +Once you have changed the tempo, you can get back the default one by doing a +double click on the <acronym>LCD</acronym>. +</para> + +</sect1> + +</chapter> + +<chapter id="key-bindings"> +<title>Key bindings</title> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> +<entry>Key</entry> +<entry>Action</entry> +</row> +</thead> +<tbody> +<row> +<entry><keycap>Space</keycap></entry> +<entry>Play the loaded song, if it isn't playing, or pause it, if it's already +playing.</entry> +</row> +<row> +<entry><keycap>Backspace</keycap></entry> +<entry>Stop playing</entry> +</row> +<row> +<entry><keycap>Right Arrow</keycap></entry> +<entry>Next song in current collection</entry> +</row> +<row> +<entry><keycap>Left Arrow</keycap></entry> +<entry>Previous song in current collection</entry> +</row> +<row> +<entry><keycap>Up Arrow</keycap></entry> +<entry>Scroll lyrics one line up</entry> +</row> +<row> +<entry><keycap>Down Arrow</keycap></entry> +<entry>Scroll lyrics one line down</entry> +</row> +<row> +<entry><keycap>Page Up</keycap></entry> +<entry>Scroll lyrics one page up</entry> +</row> +<row> +<entry><keycap>Page Down</keycap></entry> +<entry>Scroll lyrics one page down</entry> +</row> +<row> +<entry><keycap>1</keycap></entry> +<entry>Display text events</entry> +</row> +<row> +<entry><keycap>2</keycap></entry> +<entry>Display lyric events</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo></entry> +<entry>Open a song</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry> +<entry>Quit &kmid;</entry> +</row> +<row> +<entry><keycap>F1</keycap></entry> +<entry>Open this document</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</chapter> + +<chapter id="frequently-asked-questions"> +<title>Frequently Asked Questions (FAQ)</title> + +<qandaset> +<qandaentry> +<question> +<para> +What is exactly a midi file? +</para> +</question> + +<answer> +<para>A Midi file is a file that contains the information on how to play +a song, that is, it contains simply the notes, the rhythm, +velocity,&etc; This implies that the same midi file, when played in two +different devices, can produce very different results, as well as a +given staff can be played very differently by two different musicians. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I can get better sound with a mp3/wav player, why should I use &kmid;? +</para> +</question> +<answer> +<para> +Well, I cannot force anyone to use &kmid;, but a typical midi file +occupies 50 Kb. while a typical mp3 file occupies 4 Mb. (and that is a +1:80 compression ratio :-) . And with a good synthesizer device, you can +get a comparable sound quality. Even more, with a midi file, you can +change individual instruments, change the velocity of a song, &etc; so +you have more overall control. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I can't get my AWE card to work with KMid, what can I do? +</para> +</question> +<answer> +<para> +This can happen when you get a binary distribution (rpm, deb) of &kmid;. It +happens because &kmid; was compiled without awe support. If it doesn't +work, then you must download a source code distribution (for example, from +<ulink url="http://www.arrakis.es/~rlarrosa/kmid.html">&kmid;'s homepage</ulink>) +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I want to add a whole folder to a collection, but having to add the midi +files one by one is not funny. +</para> +</question> + +<answer> +<para> +I agree, that's why &kmid; supports Drag & Drop. Just open, in &konqueror;, +the folder you want to add, select all the files, drag them and drop them in +&kmid;. +</para> +<para> +Be sure to set the <guimenuitem>AutoAdd to Collection</guimenuitem> option before, so that the +files will be added to the current collection. If you don't do this, files will +be added to the Temporary Collection. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I can't follow the lyrics, it's playing too fast! +</para> +</question> +<answer> +<para> +You can press the left arrow of the tempo <acronym>LCD</acronym> to make it play +slower. Remember that you can do a double click on the <acronym>LCD</acronym> to +get the default tempo. +</para> +</answer> +</qandaentry> +</qandaset> + +</chapter> + +<chapter id="final-notes"> +<title>Final notes</title> + +<sect1 id="some-tips-and-tricks"> +<title>Some tips and tricks</title> + +<para> +I will include some tips so that you can take fully advantage from all +the features of &kmid;: +</para> + +<variablelist> +<varlistentry> +<term>Opening files</term> +<listitem> +<para>I always keep a &kde; desktop with a &konqueror; window in my root +midi folder, and &kmid; in this desktop (if playing a midi file) or +sticky (if playing a karaoke file :-)). This way, when the active +collection finishes, or I want to play some file, I just go to the +konqueror; window, select the desired files and Drag & Drop to the +&kmid;'s window. +</para> + +<para> +Suppose that you want to play some midi files, but don't want to add +them to any collection, well, just turn off the <guimenuitem>AutoAdd to +Collection</guimenuitem> option in the <guimenu>Collections</guimenu> +menu, and open the files, they will be added to the Temporary +Collection. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Another method to create a new Collection</term> +<listitem> +<para> +Suppose that you have midi files <filename>A.mid</filename>, +<filename>B.mid</filename> and <filename>C.mid</filename>. At first you +only want to play the first midi file, so you unselect +<guimenuitem>AutoAdd</guimenuitem> and open +<filename>A.mid</filename>. You get then a Temporary Collection with +only one midi file. +</para> +<para> +Then you decide to play also B and C, and make a collection with all them, what +do you do? +</para> +<para> +Easy, select <guimenuitem>AutoAdd</guimenuitem> and open +<filename>B.mid</filename> and <filename>C.mid</filename> (by any of the +multiple methods), they will be automatically added to the Temporary +Collection, that will then have <filename>A.mid</filename>, +<filename>B.mid</filename> and <filename>C.mid</filename>. At this +point, you can open the <guilabel>Organize Collections</guilabel> +dialog, select the Temporary Collection, and click on the +<literal>Copy</literal> button, enter the name of the new collection, +and you are done . You already have a new collection, which holds the +A,B and C midi files, and that is not deleted when you close &kmid;. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="hall-of-kmids-friends"> +<title>Hall of &kmid;'s friends</title> + +<para> +These are some folks who have sent me midi files or a postcard, thanks +to everyone! Hearing those songs and watching those postcards will keep +me programming more and more on &kmid;. +</para> + +<itemizedlist> +<listitem> +<para>Ola Sigurdson - <literal>Taking Care of Business</literal> (Bachman +Turner Overdrive)</para> +</listitem> +<listitem> +<para>EG Lim - A really very nice postcard from Penang.</para> +</listitem> +<listitem> +<para>Guenther Starnberger - <literal>Amadeus</literal> (Falco) and +<literal>Schrei Nach Liebe</literal> (Die Aerzte)</para> +</listitem> +<listitem> +<para>Leandro Terrés - <literal>All That She Wants</literal> and +<literal>The Sign</literal> (Ace of Base)</para> +</listitem> +<listitem> +<para>Nick Stoic - Two midi files</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="about-the-author"> +<title>About the author</title> + +<para> +&kmid; has been made by Antonio Larrosa Jiménez, in Málaga +(Spain). I am a student of Mathematics at the University of +Málaga, currently I'm doing the third course, so I don't have +much free time for my hobbies, but I always try to get some :-) . My +hobbies include : Programming, collecting midi files, playing music and +proving theorems ;-). +</para> + +<para> +If you want to know where to download midi/karaoke files, you have any +question, a bug to report, an idea or a feature you'd like to see in +&kmid; or just want to make me happy, feel free to send me an email to: +<email>larrosa@kde.org</email> or <email>antlarr@arrakis.es</email> +</para> + +<para>or write to me by snail-mail at: +</para> + +<literallayout> Antonio Larrosa Jimenez +Rio Arnoya 10 5B +Malaga (Spain) +</literallayout> + +<para> +You will really make me happy if you send me a postcard from where you +live, or a midi/karaoke file from a local music group of your country +. Everyone who sends me a postcard or a midi file will have his/her name +in the Hall of &kmid;'s friends of this file (provided they don't oppose +to this). Please contact me before sending me any midi files because I +may have it already. +</para> + +<para> +I'd like stress that &kmid; has been done completely on free time, +without any monetary support from any company nor particular. So please +keep in mind when you use it, that the only think that keep me working +on this is getting some feedback from its users (a postcard, or just an +email). +</para> + +<para> +I would like to thanks the following persons their help in developing &kmid;: +</para> + +<itemizedlist> +<listitem> +<para> +Paul J. Leonard <email>P.J.Leonard@bath.ac.uk</email> - Support for AWE +cards +</para> +</listitem> +<listitem> +<para> +Sebestyen Zoltan <email>szoli@digo.inf.elte.hu</email>- FreeBSD port and +AWE testing +</para> +</listitem> +<listitem> +<para> +Christian Esken <email>esken@kde.org</email> - For organizing the KDE +multimedia efforts +</para> +</listitem> +<listitem> +<para> +Stephan Kulow <email>coolo@kde.org</email>- Configure scripts and help +with <command>automake</command> and <command>CVS</command> +</para> +</listitem> +<listitem> +<para> +Jaroslav Kysela - Help in doing the &Linux; Ultrasound Project driver +support +</para> +</listitem> +<listitem> +<para> +Takashi Iwai and Joseph H. Buehler - Fix for AWE cards pitch being +too high +</para> +</listitem> +<listitem> +<para> +Adrian Knoth - For giving me good news and many suggestions +</para> +</listitem> +<listitem> +<para> +Kevin Street - Patch to support FreeBSD 3.0 +</para> +</listitem> +<listitem> +<para> +Thanks go also to Jose Luis Sanchez for his testing of GUS support, +Ignacio Garcia for testing the AWE support, Hans Petter Bieker, Ola +Sigurdson, Marc Diefenbruch, Peter Gritsch, Magnus Pfeffer, Urko Lusa, +Peter-Paul Witta, Thorsten Westheider, Ulrich Cordes and everyone that +sent me a patch, bug report or just an email to give me encouragement. +</para> +</listitem> +<listitem> +<para> +And of course to all the fabulous musicians over the net that keep giving +us those wonderful midi and karaoke files. +</para> +</listitem> +</itemizedlist> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +</sect1> + +<sect1 id="copyright-and-license"> +<title>Copyrights and License</title> + +<para>&kmid; is copyright Antonio Larrosa Jiménez, 1999-2001</para> + +<para>Documentation is copyright Antonio Larrosa Jiménez 1999, +2001</para> + +&underFDL; +&underGPL; + +</sect1> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="how-to-obtain-kmid"> +<title>How to obtain &kmid;</title> + +&install.intro.documentation; + +<para> +Additionally, &kmid; can be found on its homepage, which is at <ulink +url="http://www.arrakis.es/~rlarrosa/kmid.html"> +http://www.arrakis.es/~rlarrosa/kmid.html</ulink>. In the homepage, you can +follow its development, see some information about it, some screenshots, a list +of sites from where you can download more karaoke songs, &etc; +</para> + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>&kmid; requires to work:</para> + +<itemizedlist> +<listitem> +<para> +&kde;. Well, you probably already have this :-) +</para> +</listitem> +<listitem> +<para> +A sound card. A good soundcard and/or external synthesizer are +recommended, as the sound quality depends greatly in your soundcard, +it's not the same to play the music using an FM device, than using an +AWE card. +</para> + +<para> +If you don't have a soundcard, you can still compile &kmid; with +<literal>MODE_DEMO_ONLYVISUAL</literal> defined and it will run as if +you had one (but you'll get no music, of course :-( ). +</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="compilation-and-installation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +<para> +I've included some examples that are installed in <filename +class="directory">$dollar;<envar>KDEDIR</envar>/share/apps/kmid</filename> +</para> + +<para> +If you run into any problem, don't hesitate to contact any of the &kde; mailing +list, or send a report directly to me. +</para> + +</sect1> + +</appendix> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> diff --git a/doc/kmix/Makefile.am b/doc/kmix/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kmix/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kmix/index.docbook b/doc/kmix/index.docbook new file mode 100644 index 00000000..53db80b9 --- /dev/null +++ b/doc/kmix/index.docbook @@ -0,0 +1,503 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kmix;"> + <!ENTITY package "kdemultimedia"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kmix; Handbook</title> + +<authorgroup> +<author> +<firstname>Matt</firstname> +<surname>Johnston</surname> +<affiliation> +<address>&Matt.Johnston.mail;</address> +</affiliation> +</author> + +<othercredit role="developer"> +<firstname>Christian</firstname> +<surname>Esken</surname> +<affiliation><address><email>esken@kde.org</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Helio</firstname> +<surname>Chissini de Castro</surname> +<affiliation><address><email>helio@kde.org</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + + +<othercredit role="developer"> +<firstname>Stefan</firstname> +<surname>Schimanski</surname> +<affiliation><address><email>1Stein@gmx.de</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="reviewer"> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<affiliation><address>&Lauri.Watts.mail;</address></affiliation> +<contrib>Reviewer</contrib> +</othercredit> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>1996</year><year>2005</year> +<holder>Christian Esken & &Matt.Johnston;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2007-01-05</date> +<releaseinfo>2.6.1</releaseinfo> + +<abstract><para>&kmix; is an application to allow you to change the volume of +your sound card.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KMix</keyword> +<keyword>kdemultimedia</keyword> +<keyword>sound</keyword> +<keyword>volume</keyword> +<keyword>mixer</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kmix; is &kde;'s soundcard mixer program. Though small, it is +full-featured. The program should give controls for each of your +soundcards.</para> + +<para>&kmix; supports several platforms and sound drivers:</para> + +<itemizedlist> +<listitem><para> The ALSA soundcard driver.</para></listitem> +<listitem><para> All Open Sound System platforms. Explicitly tested +are &Linux;, FreeBSD, NetBSD and BSDI.</para></listitem> +<listitem><para> &Solaris; based machines.</para></listitem> +<listitem><para> &IRIX; based machines.</para></listitem> +<listitem><para> &HP-UX; based machines.</para></listitem> +</itemizedlist> + +<para>If you have both ALSA and Open Sound System drivers installed, &kmix; will use the ALSA driver.</para> + +</chapter> + +<chapter id="working-with-kmix"> +<title>Working with &kmix;</title> + +<sect1 id="basic-usage"> +<title>Basics</title> + +<para>&kmix; usage is straightforward. Every mixer control that your +soundcard provides is represented by a volume slider. Mono controls +have a single slider, stereo controls can have either one or two +sliders, depending on your choice. Additionally there is a panning +slider at the bottom of the &kmix; window. If you have more than one soundcard, a list will be displayed on the top of the window, where you can choose between your soundcards. + +<screenshot> +<screeninfo>The &kmix; Main Window</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kmix-window.png" format="PNG"/></imageobject> +<textobject><phrase>The &kmix; Main Window</phrase></textobject> +</mediaobject> +</screenshot> + +</para> + + +<para>The Window can have up to three sections with different soundcard controls: +<guilabel>Output</guilabel>, <guilabel>Input</guilabel> and <guilabel>Switches</guilabel>. +Those sections contain volume sliders, switches for enabling/disabling record or playback, and multiple-choice selectors. + +<simplelist> +<member><guilabel>Output</guilabel>: This holds the controls that are most likely playback related, like the <guilabel>Master</guilabel> volume control.</member> +<member><guilabel>Input</guilabel>: This holds all controls that are most likely record related, like <guilabel>Capture</guilabel>.</member> +<member><guilabel>Switches</guilabel>: This holds all controls, that allows only to switch some functionality ON or OFF (like "Mic Boost (+20dB)"), and multiple-choice controls (like <guilabel>Mic Select</guilabel>: <guilabel>Mic1</guilabel> or <guilabel>Mic2</guilabel>).</member> +</simplelist> +</para> + +<para>Besides volumes controls, &kmix; also features LED's. The general coloring rule is:</para> +<simplelist> +<member>Green: A LED dealing with playback</member> +<member>Red: A LED dealing with recording</member> +<member>Yellow: A LED dealing with special soundcard capabilities</member> +</simplelist> +<para>These 3 colors come in two flavours: A lit LED means ON, a non-lit LED means OFF.</para> +</sect1> + +<sect1 id="volume-sliders"> +<title>Volume controls</title> + +<para>The volume controls in section <guilabel>Output</guilabel> and <guilabel>Input</guilabel> consist of (top to bottom): +<screenshot> +<screeninfo>Volume control (<guilabel>Input</guilabel> Section)</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kmix-channel-playback.png" format="PNG"/></imageobject> +<textobject><phrase>Volume control (<guilabel>Input</guilabel> Section)</phrase></textobject> +</mediaobject> +</screenshot> + +<simplelist> +<member>An icon, representing the function of the control.</member> +<member>A volume value indicator (optional).</member> +<member>A Green Mute LED, that allows you to mute a control (light goes off/gets dark) or unmute it again (light goes on/gets bright).</member> +<member>A slider, for volume control (Hint: You can hide the label on the slider, for example if the mixer takes too much of your screen space).</member> +<member>If a control supports recording, there will be a red Record LED. If the LED is lit (bright red), the control is selected for recording. If it is not lit (dark red), the control is NOT selected for recording.</member> +</simplelist> + +<screenshot> +<screeninfo>Volume control with Recording Switch (<guilabel>Output</guilabel> Section)</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kmix-channel-record.png" format="PNG"/></imageobject> +<textobject><phrase>Volume control with Recording Switch (<guilabel>Output</guilabel> Section)</phrase></textobject> +</mediaobject> +</screenshot> + +</para> + + +<para> +Most of these controls have a context menu, accessible by right clicking on the control or device icon. Several entries are possible in the context menu, but only those applicable are shown. +</para> + +<variablelist> +<varlistentry> +<term><guimenuitem>Split Channels</guimenuitem></term> +<listitem><para>Show either one or two sliders. This is only applicable to +stereo devices. The right slider controls right side volume, and the left +controls left side volume.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Muted</guimenuitem></term> +<listitem><para>Mute or unmute the device</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Hide</guimenuitem></term> +<listitem><para>If you are not interested in regulating this device you can hide it with this option. If you want to show it again, you can only do this by selecting the <guimenuitem>Channels</guimenuitem> option (see below)</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Configure Global Shortcuts...</guimenuitem></term> +<listitem><para>You can control a device with your keyboard. Use this menu option to show the &kde; <guilabel>Configure Shortcuts</guilabel> dialog. Here you can define keys for increasing and decreasing volume and for muting the device. The keys are global and operate also when &kmix; is iconified or docked.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Channels</guimenuitem></term> +<listitem><para>You will get a dialog box where you can configure per section (<guilabel>Output</guilabel>, <guilabel>Input</guilabel>, <guilabel>Switches</guilabel>), which channels you want to see.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Show/Hide Menubar</guimenuitem></term> +<listitem><para>This option is not device specific, but affects the mixer window. You can hide and show the menubar with this option. You can also do this by pressing the shortcut (usually <keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo>)</para></listitem> +</varlistentry> + +</variablelist> +</sect1> + +<sect1 id="switches"> +<title>Switches and Multiple-Choice selectors</title> + +<para>The controls in the section <guilabel>Switches</guilabel> consist of a LED and a short label describing the function. The <guilabel>Switches</guilabel> section can also contain Multiple-Choice selectors. Please note that these controls are often very special and usually don't need to be changed by the average user. The context menu contains the <guimenuitem>Channels</guimenuitem> and <guimenuitem>Show/Hide Menubar</guimenuitem> entries already described. + +<screenshot> +<screeninfo>Switches and Multiple-Choice selectors (<guilabel>Switches</guilabel> Section)</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kmix-channel-switches.png" format="PNG"/></imageobject> +<textobject><phrase>Switches and Multiple-Choice selectors (<guilabel>Switches</guilabel> Section)</phrase></textobject> +</mediaobject> +</screenshot> + +Please remember, red LED's are recording related, yellow LED's control special soundcard capabilities. + +The screenshot above shows from left to right an unlit <guilabel>IEC958 Output</guilabel> LED (yellow = special control), a lit <guilabel>Mix</guilabel> LED (red = Recording related), an unlit recording related LED, a lit special control and one multiple-choice selector (<guilabel>PCM Out Path & Mute</guilabel>). + +If you are uncertain about the meaning of a control, please ask your soundcard driver supplier (for most current &Linux; distributions this is <ulink url="http://www.alsa-project.org">ALSA</ulink>). +</para> + +</sect1> + +<sect1 id="panning-slider"> +<title>Panning slider</title> + +<para>With this slider you can control the volume distribution between left and +right speaker. This slider is an overall regulator, which affects the Master Volume. +The middle position is the default. Dragging +the slider to the left lowers the volume of the right speaker, dragging it to +the right vice versa. Of course, these might be swapped if your speakers aren't +positioned correctly.</para> +<para>For Surround Systems please be aware that the <guilabel>Master</guilabel> device often regulates only the Front Speakers. +This is a limitation of your Soundcard driver.</para> +<para>If your soundcard has no <guilabel>Master</guilabel> device, some other device might get picked by &kmix; - for most people this is the <guilabel>Wave</guilabel> (or <guilabel>PCM</guilabel>) control.</para> + +</sect1> + +<sect1 id="configuration-options"> +<title>Configuration options</title> + +<para>Use <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kmix;...</guimenuitem></menuchoice> +from the menubar to choose preferences. These items are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Dock into panel</guilabel></term> +<listitem><para>If checked, &kmix; will dock in the systray when pressing the window close button. If not checked, &kmix; will quit on pressing the window close button. Attention: After quitting you will not be able to control the volume if you have assigned keys for this.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Enable system tray volume control</guilabel></term> +<listitem><para>If enabled, a left-clicking the &kmix; dock icon will show a popup window with a volume control for the preferred device (Hint: currently you cannot change this device - it is selected by &kmix; instead). If the option is disabled, the &kmix; Main Window will be shown on a left-click on the &kmix; dock icon.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show tickmarks</guilabel></term> +<listitem><para>Show lines to mark positions on the sliders.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show labels</guilabel></term> +<listitem><para>Display labels for each of the sound devices. Wether this item +is checked or not, by holding the mouse over the icon for each device, you can see this information.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Restore volumes on login</guilabel></term> +<listitem><para>Let &kde; restore the volumes when you Login: This restores your personal volume levels, stored when you last logged out. If your Operating System saves the volume levels, you might not need this option (but on a computer with multiple users it is still needed).</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Volume Values:</guilabel></term> +<listitem><para>Select if and how volume values are displayed: <guilabel>None</guilabel>, <guilabel>Absolute</guilabel> or <guilabel>Relative</guilabel>.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Slider Orientation</guilabel></term> +<listitem><para>With this option you can turn the &kmix; main window content by 90 degrees. Sliders, texts and everything else (if applicable) is rotated. There are some exclusions to this rule, most notably the menubar, the mixer selector (if shown at all), the panning slider and the multiple-choice selectors.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + + +</chapter> + + +<chapter id="working-with-kmixapplet"> +<title>The &kmix; panel applet</title> + +<para> +The &kmix; panel applet is an alternative interface to &kmix;. +You can add it to the &kde; panel by selecting <guimenuitem>Add Applet to Panel...</guimenuitem> in the <guimenu>Panel Menu</guimenu> or context menu. +Choose <guilabel>Sound Mixer</guilabel> and click the <guibutton>Add to Panel</guibutton> or double click <guilabel>Sound Mixer</guilabel>. +</para> + +<para> +You can work with the &kmix; applet as described for the <link linkend="working-with-kmix">main window</link> - including the context menu. +Due to the limited space in the panel there are differences: + +<simplelist> +<member>No main menu available.</member> +<member>If you have multiple soundcards, you cannot change the selected mixer after the initial selection.</member> +<member>No dock icon. If you want to use the dock item you must additionally start &kmix; with +<menuchoice><guimenu>K-Menu</guimenu><guisubmenu>Multimedia</guisubmenu><guimenuitem>&kmix; Sound Mixer</guimenuitem></menuchoice>.</member> +<member>Icons only available when panel is big enough.</member> +<member>No device name labels available.</member> +<member>Configuration is done via panel menu - you can configure colors and slider direction there.</member> +<member>No automatic volume saving. If you want your volumes saved when you logout for later restauration, you must also start &kmix; from the K-Menu.</member> +</simplelist> + +</para> +</chapter> + + +<chapter id="advanced-kmix"> +<title>Advanced &kmix; features</title> + +<warning><para>This chapter describes &kmix; functionality that is targeted at the experienced user. Most users will never have a need for this functionality, so you can safely skip this chapter</para></warning> + +<sect1 id="dcop-overview"> +<title>The &DCOP; Interface</title> + +<para> +Sometimes you want to do specialized things. +Things like controlling the mixer from another application or muting the master device every day at 10pm. +&kmix; has a &DCOP; interface that allows you to achieve much with minimal work. +You can start a shell and type <userinput><command>dcop kmix</command></userinput> to start exploring the &kmix; &DCOP; interface. +The &kmix; specific interfaces are:</para> + +<variablelist> +<varlistentry> +<term><userinput><command>Mixer0</command></userinput></term> +<listitem><para>Allows manipulating the first mixer. You can set volume levels, mute the device, change balance, retrieve the mixer name and much more. Type <userinput><command>dcop kmix Mixer0</command></userinput> if you want to explore all the features. There are more entries like <userinput><command>Mixer1</command></userinput> in case multiple soundcards are installed.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kmix-mainwindow#1</command></userinput></term> +<listitem><para>The &GUI; window can be controlled with this command. You can hide and show the window, resize it and much more. Type <userinput><command>dcop kmix kmix-mainwindow#1</command></userinput> if you want to explore all the features.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + + +<sect1 id="dcop-examples"> +<title>&DCOP; Examples</title> + +<variablelist> +<varlistentry> +<term><userinput><command>dcop kmix kmix-mainwindow#1 hide</command></userinput></term> +<listitem><para>Hides the &GUI; window. Use <userinput><command>dcop kmix kmix-mainwindow#1 show</command></userinput> or the dock icon to show it again.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>dcop kmix kmix-mainwindow#1 resize 1 1</command></userinput></term> +<listitem><para>Resizes the &GUI; window to the smallest size possible. This is the size so that all sliders (and other &GUI; elements) will fit into the window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>dcop kmix Mixer0 mixerName</command></userinput></term> +<listitem><para>Tells the name of the first Mixer, for example <computeroutput>Sound Fusion CS46xx</computeroutput>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>dcop kmix Mixer1 setVolume 0 10</command></userinput></term> +<listitem><para>Sets the volume on the second mixer, device 0 to 10 percent. Device 0 is often the master device, but not always. If you want to quiet down the (first) master device on your second soundcard, you can use <userinput><command>dcop kmix Mixer1 setMasterVolume 0</command></userinput></para></listitem> +</varlistentry> +</variablelist> + +<para>You can directly execute these commands from a shell that you started from inside &kde;. If you need to execute dcop commands from somewhere else, for example from a crontab script, you need to define the <envar>DCOPSERVER</envar> environment variable (as seen in the first line of your <filename>~/.DCOPserver_hostname_:0</filename> file), for example:</para> + +<programlisting> +#!/bin/sh +DCOPSERVER=`cat /home/yourhome/.DCOPserver_yourhostname_:0 | grep local` +export DCOPSERVER +dcop kmix Mixer0 setMasterVolume 0 +</programlisting> +</sect1> + +<sect1 id="tips-and-tricks"> +<title>Tips and Tricks</title> +<sect2> +<title>Using ALSA and OSS driver at the same time</title> +<para>&kmix; on &Linux; can use either the ALSA driver or the OSS driver, not both. If you really need to use both drivers at the same time (a very rare situation), you can do it as follows: Quit &kmix; and add the following line to your <filename>kmixrc</filename> file in the global configuration section.</para> +<programlisting>MultiDriver=true</programlisting> +<para>Start &kmix; again. If you click <menuchoice><guimenu>Help</guimenu><guimenuitem>Hardware Information</guimenuitem></menuchoice> you should see <guilabel>Sound drivers used: ALSA0.9 + OSS</guilabel> and <guilabel>Experimental multiple-Driver mode activated</guilabel>.</para> + +<warning><para>You will probably see all of your mixers doubled.</para> +<para>There is no support for this kind of configuration.</para></warning> +</sect2> + +</sect1> + +</chapter> + +<chapter id="credits"> +<title>Credits and License</title> + +<para>Main developers</para> + +<itemizedlist> +<listitem><para>Copyright 1996-2000 Christian Esken</para></listitem> +<listitem><para>Copyright 2000-2003 Christian Esken & Stefan Schimanski</para></listitem> +<listitem><para>Copyright 2003-2005 Christian Esken & Helio Chissini de Castro</para></listitem> +</itemizedlist> + +<para>Contributors:</para> + +<itemizedlist> +<listitem><para>Christian Esken <email>esken@kde.org</email></para></listitem> +<listitem><para>Stefan Schimanski <email>1Stein@gmx.de</email></para></listitem> +<listitem><para>Paul Kendall <email>paul@orion.co.nz</email> - &SGI; +Port</para></listitem> +<listitem><para>Sebestyen Zoltan <email>szoli@digo.inf.elte.hu</email> - FreeBSD +Fixes</para></listitem> +<listitem><para>Faraut Jean-Louis <email>jlf@essi.fr</email> - &Solaris; +Fixes</para></listitem> +<listitem><para>Nick Lopez <email>kimo_sabe@usa.net</email> - ALSA +Port</para></listitem> +<listitem><para>&Helge.Deller; <email>deller@gmx.de</email> - &HP;-UX +Port</para></listitem> +<listitem><para>Lennart Augustsson <email>augustss@cs.chalmers.se</email> - *BSD +Fixes</para></listitem> +</itemizedlist> + +<para>Documentation copyright 2000 &Matt.Johnston; +&Matt.Johnston.mail;</para> + +<para>Updated 2003 to match &kmix; V1.91 by Christian Esken +<email>esken@kde.org</email></para> + +<para>Updated 2005 to match &kmix; V2.2 by Christian Esken +<email>esken@kde.org</email></para> + +<para>Updated 7/2005 to match &kmix; V2.6 by Christian Esken +<email>esken@kde.org</email></para> + +<para>Based on documentation by Christian Esken +<email>esken@kde.org</email></para> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kmix"> +<title>How to obtain &kmix;</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>Obviously, &kmix; is only of use if you have a soundcard. +&kmix; supports several platforms and sound drivers:</para> + +<itemizedlist> +<listitem><para> All Open Sound System platforms. Explicitly tested +are &Linux;, FreeBSD, NetBSD and BSDI.</para></listitem> +<listitem><para> &Solaris; based machines.</para></listitem> +<listitem><para> &IRIX; based machines.</para></listitem> +<listitem><para> The ALSA soundcard driver.</para></listitem> +<listitem><para> &HP-UX; based machines.</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</sect1> + +</appendix> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/kmix/kmix-channel-playback.png b/doc/kmix/kmix-channel-playback.png Binary files differnew file mode 100644 index 00000000..11e65ae0 --- /dev/null +++ b/doc/kmix/kmix-channel-playback.png diff --git a/doc/kmix/kmix-channel-record.png b/doc/kmix/kmix-channel-record.png Binary files differnew file mode 100644 index 00000000..7d1d3b39 --- /dev/null +++ b/doc/kmix/kmix-channel-record.png diff --git a/doc/kmix/kmix-channel-switches.png b/doc/kmix/kmix-channel-switches.png Binary files differnew file mode 100644 index 00000000..497a12a5 --- /dev/null +++ b/doc/kmix/kmix-channel-switches.png diff --git a/doc/kmix/kmix-window.png b/doc/kmix/kmix-window.png Binary files differnew file mode 100644 index 00000000..ab473dd7 --- /dev/null +++ b/doc/kmix/kmix-window.png diff --git a/doc/krec/Makefile.am b/doc/krec/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/krec/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/krec/index.docbook b/doc/krec/index.docbook new file mode 100644 index 00000000..38665c91 --- /dev/null +++ b/doc/krec/index.docbook @@ -0,0 +1,639 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&krec;"> + <!ENTITY package "kdemultimedia"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &krec; Handbook</title> + +<authorgroup> +<author> +<firstname>Arnold</firstname> +<surname>Krille</surname> +<affiliation> +<address><email>arnold@arnoldarts.de</email></address> +</affiliation> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +<copyright> +<year>2002</year> +<year>2003</year> +<year>2004</year> +<holder>Arnold Krille</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-03-01</date> +<releaseinfo>0.5.1</releaseinfo> + +<!-- + vim: tw=80 et sw=2 ts=2 +--> +<abstract> +<para> +&krec; is a recording application for &arts;. It can be used to record any +sound coming into or out of the computer. Some effects for dynamics are +implemented as well as the possibility to play out what is recorded. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdemultimedia</keyword> +<keyword>KRec</keyword> +<keyword>aRts</keyword> +<keyword>recording</keyword> +<keyword>frontend</keyword> +</keywordset> + +</bookinfo> + +<!-- + TODO: (ordered by priority) + - Explained: + - Mainwidget + - more on exports + + Quality settings + + possible more examples for the compressors + + Configuration + + Recording from line-in +--> + +<chapter id="introduction"> +<title>Introduction</title> + +<sect1 id="why-krec"> +<title>Why I wrote &krec;</title> + +<para> +After working with &arts; for some time I realized that there is no recording +application for it except the command line tool <command>artsrec</command>. +I had to record a radio play some friends of mine wanted me to mix and +master and I wanted to use &Linux; for the recording. So I started +writing &krec;. +</para> +</sect1> + +<sect1 id="what-krec-does"> +<title>What &krec; does</title> + +<para> +&krec;'s function is quite simple. It connects to the &arts; server and records +what is routed to it into files. These files are in a special &krec; format but +it is possible to export to wave, ogg and mp3 files. +</para> +<para> +But &krec; has much more functionality. You can do multiple recordings in one +file even with overlaying functionality. +</para> +</sect1> + +<sect1 id="bugs_and_info"> +<title>Getting more info</title> +&reporting.bugs; +&updating.documentation; +</sect1> + +</chapter> + +<chapter id="first_glance"> +<title>A first glance at &krec;</title> + +<!--<para> +Let`s take a first glance at &krec; right after startup and I will try to give +some explainations what the different items are. +</para>--> + +<screenshot> +<screeninfo>Here's a screenshot of &krec;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="krec-keramik.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Here is a screenshot of &krec; right after it started.</phrase> +</textobject> +</mediaobject> +</screenshot> + +<sect1 id="first_glance_items"> +<title>The &krec;-mainwindow in detail</title> + +<itemizedlist> +<listitem><para>At the top there is the <emphasis>menubar</emphasis> and two +<emphasis>toolbars</emphasis>. The first toolbar contains some usefull items +from the <guimenu>Files</guimenu>-menu, the second toolbar is shipped with +important functions from the <guimenu>Play</guimenu>-menu.</para></listitem> +<listitem><para>The middle has the important parts: On the left is the VU-Meter +displaying the volume of the audiosignal currently recorded/played combined +with a volumecontrol to adjust the level.</para></listitem> +<listitem><para>The main part shows the file and consists of four parts. First +at the top is the name of the file, the second shows the parts recorded in their +chronological order and scaled length. It also allows to disable or delete +parts via contextmenu. Below is the time line where you can see the current +position and (by clicking) move to the position you want. The bottom of this +block are two widgets showing the current position and the length in the +timeformat you want.</para></listitem> +<listitem><para>At the overall bottom there is another toolbar containing a +compressor to edit the dynamics of your recording and a statusbar showing all +kinds of messages.</para></listitem> +</itemizedlist> + +<para> +See <xref linkend="krec_explained" /> for more info. +</para> + +</sect1> +</chapter> + +<chapter id="recording_howtos"> +<title>Howto record</title> + +<para> +This chapter contains some step-by-step tutorials which show you the way to go +for some good recordings with &krec;. +</para> + +<sect1 id="recording_from_music"> +<title>Recording from internal music</title> + +<orderedlist> +<listitem><para> +The first thing to do is a recording from our favourite &kde; +audioplayer. So start &noatun;, &juk; <!--JuK--> or &kaboodle;. We could +use other players but they have to use &arts; for their output, otherwise +recording is a bit more complex and beyond the scope of this section. So please +jump over your shadow and select a song to play in one of this three players +(all are shipped with kdemultimedia where you got &krec; +from). +</para></listitem> +<listitem><para> +In &krec; select the <guimenuitem>Audio Manager</guimenuitem> from the +<guimenu>Tools</guimenu>-menu. There you will see at least a line for &krec;::In +and a line for &krec;::Out. The second column says what type the item is, either +<emphasis>play</emphasis> or <emphasis>record</emphasis>. The last column says +where the sound for this item comes from or goes to. Currently the &krec;::In +item is (should be?) connected to <emphasis>in_soundcard</emphasis> which is the +input channel of your soundcard but as we currently want to record from the +player and the player plays to <emphasis>out_soundcard</emphasis>, we click on +the &krec;::In item to switch it to another source. Select +<emphasis>out_soundcard</emphasis> from the upcoming window and click +<guibutton>Ok</guibutton>. To learn more about the audio manager see <xref +linkend="audio_manager" />. +</para></listitem> +<listitem><para> +Now the VU-Meter in &krec; should flicker up and down in a way corresponding to +the music your hear (if you don't hear sound you shouldn't expect the VU to show +something). +</para></listitem> +<listitem><para> +Now open a new file either by clicking on the first item in the toolbar or by +selecting <guimenuitem>New</guimenuitem> from the +<guimenu>Files</guimenu>-menu. Accept the quality settings for now or see <xref +linkend="quality" /> for more info. +</para></listitem> +<listitem><para> +Select <guimenuitem>Record</guimenuitem> from the <guimenu>Play</guimenu>-menu +or press the <keycap>R</keycap>-key. After you are finished select +<guimenuitem>Stop</guimenuitem> from the same menu or use the +<keycap>S</keycap>-key. +</para></listitem> +<listitem><para>Saving works the standard way, if you are interested in +exporting see <xref linkend="exporting" />.</para></listitem> +</orderedlist> + +<para> +Thats it! Now you can hear your recording or export it (don`t forget to go back to the +beginning). +</para> + +</sect1> + +<sect1 id="recording_from_line_in"> +<title>Recording from Line-In or Mic-In</title> + +<para> +Recording outside-sources is a bit more complicated as it involves a lot of +different applications and hardware devices. I am assuming your hardware is +installed correctly, the drivers are working as they should and you are able to +control the hardware volumes via &kmix;. In &kmix; you can also select channels +for recording which basicly means that their signal is sent to the +analog-digital-converter (short ADC) and can be read by the driver and applications. This +works differently on almost all soundcards and drivers so you have to try a bit +before you can be sure... +</para> +<para> +Second important thing is that &arts; has to run in full-duplex mode. That means +that &arts; is reading from the soundcard and writing to it at the same time. +You have to start &kcontrol; and edit the soundsystem settings (or press Alt+F2 +and enter <command>kcmshell arts</command>). On the second tab-page you have to +make sure the checkbox for full-duplex is selected, clicking +<guibutton>Apply</guibutton> restarts &arts; which means that you have to restart +&krec; too. +</para> +<para> +After these preparations the VU-Meter (see <xref linkend="vu-meter" /> for more +info) of &krec; should flicker according to the +audio-signal you want to record and which you have selected for recording in +&kmix;. Adjusting the volume to the right values is very important for usable +recordings. If the amplification inside the soundcard is to high you get digital +crackles because the <glossterm>ADC</glossterm> can only create values between a +minimum and a maximum and if the signal is to loud it gets digitally clipped +which ruins the recording. On the other hand if the volume is to silent you get +the noise and hiss from the audio-hardware to loud into your recording. So you +have to choose a middle-way so the signal is not to loud and gets clipped but +not to silent to get lost in the noise of the hardware. Its almost always better +to leave some headroom. +</para> +<para> +Now you can adjust the level a second time in &krec; which then is a software +amplification. Here it is best to use the compressor to equalize the differences +between silent and loud parts a bit. More info on compressor usage can be found +in <xref linkend="compressor" />. +</para> +<para> +The remaining steps are the same as in <xref linkend="recording_from_music" /> +from step four and following. So if you started with that section you should +know it now. +</para> + +</sect1> +</chapter> + +<chapter id="krec_explained"> +<title>&krec; explained</title> + +<para> +This chapter describes some parts and functions of &krec; in detail and gives +some tips on usage. The items are sorted alphabeticly, not by importance. +</para> + +<sect1 id="audio_manager"> +<title>The Audio Manager</title> +<para> +The audio manager is used to connect the outputs from different applications to +existing or new busses. A bus is some kind of a virtual signal distributor. +Every play- or record-item can connect to exactly one bus but multiple items can +connect to a bus. Example: The output of &noatun; can connect to the main out +<emphasis>or</emphasis> any other bus. But multiple &noatun;s can all connect to the main out. +</para> + +<sect2 id="audio_manager_mw"> +<title>The main window of the Audio Manager</title> +<para> +It contains three columns: +</para> +<orderedlist> +<listitem><para>The name of the item playing or recording sound.</para></listitem> +<listitem><para>The type of the item either <emphasis>play</emphasis> or +<emphasis>record</emphasis>.</para></listitem> +<listitem><para>The bus the item is connected to.</para></listitem> +</orderedlist> +<para> +Click on an item and a dialog for choosing the wanted bus pops up. +</para> +</sect2> +<sect2 id="audio_manager_dialog"> +<title>The Busdialog</title> +<para> +The main part shows all currently existing busses. Select one to send your audio +to it or get your audio from it. Below you can create new busses to connect your +item to. +</para> +<tip><para> +To record from an &arts;-aware-player and listening to what you actually record +just create a new bus (<emphasis>test</emphasis> for example), connect your +player to it (you wont hear anything now), connect &krec;::In to the new bus +too and then turn on the <guimenuitem>Play Through</guimenuitem>. +</para></tip> +</sect2> + +</sect1> + +<sect1 id="compressor"> +<title>The Compressor</title> +<para> +If you are recording with a microphone you might notice that the level is +sometimes almost clipped and sometimes very low especially +singing or speeching voices. To correct this you can use the compressor. It +simply reduces all sound that is over the given <emphasis>threshold</emphasis> +by the factor given as <emphasis>ratio</emphasis>. Note that the threshold is +logarithmic, a mid setting is already relativ low but thats very usable that +way. Another note: ratio is at its highest turned to the left, the right end of +the poti means no compression at all. As this reduces the loudness there is a +<emphasis>output</emphasis> potentiometer to expand (or reduce) the sound. +<emphasis>attack</emphasis> and <emphasis>release</emphasis> let you control the +time after which the compressor reacts (the time going by after input first +exceeds the threshold) and the time the compressor still reacts after sound is +below the threshold. +</para> +<tip><para>Test it while you are speaking into your microphone with <guimenuitem>Play +Through</guimenuitem> enabled and you will hear the difference between the +plain and a compressed version.</para></tip> +<sect2 id="compressor_tips"> +<title>Tips for compressor usage</title> +<para> +These are <emphasis>only</emphasis> tips. In the end the only thing that counts +is how it sounds. So if it sounds as you want it, its probably the right +setting. And don't hesitate to do some experiments. +</para> +<glosslist> +<glossentry><glossterm>Normal speech</glossterm><glossdef><para>Most times a +single voice speaking for radio or television is very heavily +compressed. Because the main problem of speech is that the level is perhaps +the right way at the beginning of the sentence but probably not at the +end. Additionaly the wordendings are less loud than the start. That makes it impossible to use spoken +words without compressing it. Examplesettings: Short attack, mid-time release, +low threshold, very high ratio.</para></glossdef></glossentry> +<glossentry><glossterm>Mastering 1: Limiting the +level</glossterm><glossdef><para>To just limit peaks but not compress whole +dynamics use a high threshold, a high ration, a short attack and a short-to-mid +release. This protects your recording from some internal digital distortion and, +with the treshold a bit lower, removes rare (and perhaps unwanted) peakes and +gives more room for the actual recorded signal.</para></glossdef></glossentry> +<glossentry><glossterm>Mastering 2: Doing real +mastering</glossterm><glossdef><para>Doing real Mastering of music is difficult +and depends totally on your hearing and the music that is to be mastered. +Normally you will use fast attacks sou you get the level reduced fast enough at +the bass drum beat. On the other hand you don't want the music to be pumping up +and down just because of the bass drum beats so you select a longer release. The +compression factor shouldn't be much. Ideally you would plug a limiter after the +compressor to be free of clicks and clippings.</para></glossdef></glossentry> +<glossentry><glossterm>Single Instruments</glossterm><glossdef><para>These +settings depend on the instrument. While recording it is wise to use a +limitersetting.</para></glossdef></glossentry> +<glossentry><glossterm>Final tip</glossterm><glossdef><para>Use your ears and +do some practicing. Anything is allowed if it sounds right!</para></glossdef></glossentry> +<!--<glossentry><glossterm>Term</glossterm><glossdef><para>Definition</para></glossdef></glossentry>--> +</glosslist> +</sect2> +</sect1> + +<sect1 id="configuration"> +<title>Configuration</title> +<para> +Two pages are available at the configuration. The first one is for general +settings and explained in this section. The second is about the default quality +settings and the same as described in <xref linkend="quality" />. +</para> +<screenshot> +<screeninfo>General settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="krec-configuration.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Editing general &krec; settings.</phrase> +</textobject> +</mediaobject> +</screenshot> +<para> +The first part are settings controlling the way time and positions are +displayed. The style "Plain samples" just shows the number of samples, the next +one has optionally hours, minutes, seconds and samples. The third style is the +same as the second except that it shows frames instead of the samples. The +fourth style shows the size in megabyte and kilobyte and usefull for controlling +diskspace. On the right side of the styles you have the opportunity to select +the number of frames forming one second. +</para> +<para> +The checkbox below makes the timedisplays be more verbose and showing the unit +within. +</para> +<para> +If you want to restore the tip of the day at startup you can do so with the next +checkbox. The button below it brings back all the messages where you did select +"Don't show this message again", mostly messages fom the export functions. +</para> +</sect1> + +<sect1 id="exporting"> +<title>Exporting</title> +<blockquote> +<attribution>An anonymous fan of &krec;</attribution> +<para>Your app is very cool, I use it all my day but it really lacks exporting to +wave/mp3/ogg!</para> +</blockquote> +<para> +Here it is: the definitiv export functionality for &krec;. The available export +formats vary on the libraries found at compiletime, all currently available ones +are described in the following sections. +</para> +<para> +Selecting the wanted exportplugin is done via the filename: You select +<guimenuitem>Export File...</guimenuitem> from the <guimenu>Files</guimenu>, +choose the filename for the exported file and its extention and the plugin is +determined from your extention. The list of extentions in the dialog also shows +which exportplugins are available. +</para> +<para> +For understanding the general usage of export: Technically exporting works like +playing. That means that you have to go to the position where you want to start +the exporting before doing it. It also means that you can see the progress of +the exportation from the current position marker moving forward. And it means +that in the future its possible to export every selection you like just like +playing only a selection. +</para> +<sect2 id="export_wave"> +<title>Exporting to Wave (*.wav)</title> +<para> +The simpliest exportplugin. It exports your &krec; file to +a wave file with the quality settings you made for the whole file. +</para> +</sect2> +<sect2 id="export_mp3"> +<title>Exporting to MP3 (*.mp3)</title> +<para> +Maybe the most-wanted export possibility. This one exports your &krec;-file into +a mp3-file. +</para> +<important><para> +The qualitysettings you set up in &kcontrol; section +<quote>Sound & Multimedia</quote> / <quote>Audio CDs</quote> are used in +this version since &krec; also uses the same libraries as the audiocd:/-feature. +</para></important> +</sect2> +<sect2 id="export_ogg"> +<title>Exporting to OGG (*.ogg)</title> +<para> +This one exports your &krec;-file into an ogg-file. +</para> +<important><para> +The qualitysettings you set up in &kcontrol; section +<quote>Sound & Multimedia</quote> / <quote>Audio CDs</quote> are used in +this version since &krec; also uses the same libraries as the audiocd:/-feature. +</para></important> +</sect2> +</sect1> + +<sect1 id="play_thru"> +<title>Play through</title> +<para> +For those who want to hear what they are recording there is the very useful +<guimenuitem>Play-Through</guimenuitem> option in the menu +<guimenu>Play</guimenu>. I advise using it as much as possible especially if you +do things like using the compressor or other effects and want to control what +actually is recorded. +</para> +<caution><para> +Be sure to not build a feedback loop while recording from +<emphasis>out_soundcard</emphasis> and activating +<guimenuitem>Play-Through</guimenuitem>. Such a loop is way to much for poor +&arts; and it slows your system heavily down! You might kill &arts;... +</para><para> +The reason is that &arts; calculates a network for audio for every sample +(acually blocks of samples) and if on sample is build via a loop from itself +&arts; has to calculate more than is possible. +</para></caution> +</sect1> + +<sect1 id="quality"> +<title>Quality settings</title> +<screenshot> +<screeninfo>The properties for new files</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="krec-new_file_properties.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>This is the dialog for choosing the properties for new files.</phrase> +</textobject> +</mediaobject> +</screenshot> +<para> +While creating a new &krec;-file this dialog is displayed and lets you choose +some settings for the quality of the recordings. All of these settings have an +impact on the size. +</para> +<para> +The <emphasis>sampling rate</emphasis> is the rate which tells audiosystem how +many samples to take during a second and is measure in Hertz (Hz) respectivly +Kilohertz (kHz). The higher this rate the higher is the maximum recorded +frequency. Since at least two samples are needed to rebuild a +<quote>sinus</quote>-wave the maximum recording frequency is half of the +sampling rate. The human ear is capable of hearing tones up to something between +10kHz and 20kHz depending on the age, little children are possibly nearer to +20kHz while normal adults have their maximum around 15kHz and elder people go +down to 10kHz. But even without actually hearing the higher frequencies they +still have an impact on what is heared and felt (corresponding keyword: psycho +acoustics). +</para> +<para> +The number of channels can be freely choosen depending on the task of the +recording. If you are using a mono-microphone without applying a stereo effect +you can safely choose <quote>Mono</quote> without the loss of data. +</para> +<para> +The last part are the number of bits used for one sample, possible values are 8 +and 16 bits. The more bits the more steps are available for the range from +minimum and maximum signal. 8 bits are one byte so this can also be referred to +as one byte or two byte samples. +</para> +<para> +The space needed for the recording can be calculated in a very simple way: Its +the sampling rate multiplied by the number of channels multiplied by the number +of bytes per sample multiplied by the number of seconds wanted to record. +</para> +<example><title>Calculating the size of one minute CD quality</title><para> +For one minute (60 seconds) audio in CD quality (44100Hz, 16bits, stereo) the +space needed is: 44100 * 2 * 2 * 60 = 1058400 Bytes = 10335.938 Kilobytes. That +is around 10 MByte of data per minute. +</para></example> +<tip><para> +Always use the best needed quality! Reducing the quality later on is always +possible, but enhancing the quality is not possible since then more data as +available is needed. +</para></tip> +<para> +The last item above the button is a checkbox for using the entered values +as defaults for every new file without showing this dialog again. +</para> +<para> +As the same dialog is also available in the configuration to choose the standard +settings, the "Use defaults..." checkbox is also accessible from there to get +the dialog for every file back. +</para> +</sect1> + +<sect1 id="vu-meter"> +<title>VU-Meter</title> +<para> +As the compressor is probably not necessary for every task the vu-meter with its +builtin volumecontrol is the most needed part of &krec; for recordings. It shows +the actual level that is recorded to the file after the used effects and +after the volume set with the control. If it is deep red most of the time +the recording is probably clipped and doesn't sound nice. If it flickers around +the bottom 2% its probably not much you will hear in your recording. +</para> +<tip><para> +For good recordings the level should be between -12dB and 0dB most of the time. +</para></tip> +<tip><para> +Use the compressor for editing the dynamics of your recordings. See <xref +linkend="compressor" /> for more info. +</para></tip> +</sect1> + +</chapter> + + + +<chapter id="credits"> +<title>Credits and License</title> +<para> +&krec; +</para> +<para> +Program copyright 2002-2003 Arnold Krille<email>arnold@arnoldarts.de</email> +</para> +<para> +Documentation copyright 2002-2004 Arnold Krille <email>arnold@arnoldarts.de</email> +</para> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> +&underFDL; +&underGPL; +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-krec"> +<title>How to obtain &krec;</title> +&install.intro.documentation; +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> +<para> +In order to successfully use &krec; 0.5.1, you need &kde; 3.3. +</para> +<para> +&krec; should be within your kdemultimedia package. As this package needs a +running &kde; and &arts; too, everything should be fine. +</para> +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> +&install.compile.documentation; +</sect1> + +</appendix> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +End: +--> diff --git a/doc/krec/krec-configuration.png b/doc/krec/krec-configuration.png Binary files differnew file mode 100644 index 00000000..2dabbdf0 --- /dev/null +++ b/doc/krec/krec-configuration.png diff --git a/doc/krec/krec-hicolor.png b/doc/krec/krec-hicolor.png Binary files differnew file mode 100644 index 00000000..d8b8fcbf --- /dev/null +++ b/doc/krec/krec-hicolor.png diff --git a/doc/krec/krec-keramik.png b/doc/krec/krec-keramik.png Binary files differnew file mode 100644 index 00000000..0fa4b174 --- /dev/null +++ b/doc/krec/krec-keramik.png diff --git a/doc/krec/krec-new_file_properties.png b/doc/krec/krec-new_file_properties.png Binary files differnew file mode 100644 index 00000000..676a58b0 --- /dev/null +++ b/doc/krec/krec-new_file_properties.png diff --git a/doc/kscd/Makefile.am b/doc/kscd/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kscd/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kscd/index.docbook b/doc/kscd/index.docbook new file mode 100644 index 00000000..25c61904 --- /dev/null +++ b/doc/kscd/index.docbook @@ -0,0 +1,932 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kscd;"> + <!ENTITY package "kdemultimedia"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kscd; Handbook</title> + +<authorgroup> + +<author> +<firstname>Mike</firstname> +<surname>McBride</surname> +<affiliation><address>&Mike.McBride.mail;</address></affiliation> +</author> + +<author> +<firstname>Jonathan</firstname> +<surname>Singer</surname> +<affiliation><address>&Jonathan.Singer.mail;</address></affiliation> +</author> + +<author> +<firstname>David</firstname> +<surname>White</surname> +<affiliation><address><email>a9403784@unet.univie.ac.at</email></address> +</affiliation> +</author> + +<othercredit role="developer"> +<firstname>Bernd</firstname> +<othername>Johannes</othername> +<surname>Wuebben</surname> +<affiliation><address>&Bernd.Johannes.Wuebben.mail;</address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Dirk</firstname> +<surname>Forsterling</surname> +<affiliation><address><email>milliByte@gmx.net</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Dirk</firstname> +<surname>Foersterling</surname> +<affiliation><address><email>milliByte@gmx.net</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="reviewer"> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<affiliation><address>&Lauri.Watts.mail;</address></affiliation> +<contrib>Reviewer</contrib> +</othercredit> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2000</year><year>2004</year> +<holder>J Singer</holder> + +</copyright> +<copyright> + +<year>2005-2006</year> +<holder>Mike McBride</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + + +<date>2005-12-22</date> +<releaseinfo>1.5</releaseinfo> + +<abstract> +<para>&kscd; is a small, fast, <abbrev>CDDB</abbrev> enabled audio +<abbrev>&CD;</abbrev> player for &UNIX; platforms.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdemultimedia</keyword> +<keyword>kscd</keyword> +<keyword>music</keyword> +<keyword>CD</keyword> +<keyword>audio</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kscd; is a fast, <acronym>CDDB</acronym> enabled &CD; player for the &UNIX; +platform. &kscd; stands for <quote>The KDE Project's small/simple &CD; +player</quote>.</para> + +<para><emphasis>New</emphasis>: the <filename>workman2cddb.pl</filename> Perl +script provided in order to facilitate transition for users of workman.</para> + +<para>I hope you will enjoy this &CD; player.</para> + +<para>&Bernd.Johannes.Wuebben;</para> + +<para>&Bernd.Johannes.Wuebben.mail;</para> + +<sect1 id="supported-platforms"> +<title>Supported Platforms</title> + +<para>&kscd; explicitly supports the following platforms:</para> + +<itemizedlist> +<listitem><para>&Linux;</para></listitem> +<listitem><para>FreeBSD</para></listitem> +<listitem><para>NetBSD</para></listitem> +<listitem><para>BSD386</para></listitem> +<listitem><para>Sun</para></listitem> +<listitem><para>&Solaris; (including <acronym>cdda</acronym> +support)</para></listitem> +<listitem><para>&HP-UX;</para></listitem> +<listitem><para>&SGI; Irix (including <abbrev>cdda</abbrev> +support)</para></listitem> +<listitem><para>Sony NEWS</para></listitem> +<listitem><para>OSF/1</para></listitem> +<listitem><para>Ultrix</para></listitem> +</itemizedlist> + +<para>and should compile on many others with few modifications.</para> + +</sect1> + +</chapter> + +<chapter id="onscreen-fundamentals"> +<title>Onscreen fundamentals</title> + +<sect1 id="basic-operation"> +<title>Basic Operation</title> + +<screenshot> +<screeninfo>The &kscd; Interface</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kscd.png" format="PNG"/></imageobject> +<textobject><phrase>The &kscd; Interface</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This is the main window of &kscd;. You should see something like this when +you start &kscd;. The controls in this window are explained below, in no +particular order.</para> + +<sect2 id="control-panel"> +<title>The Control Panel</title> + +<screenshot> +<screeninfo>The Control Panel</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd2.png" format="PNG"/></imageobject> +<textobject><phrase>The Control Panel</phrase></textobject> +</mediaobject> +</screenshot> + +<para> This is the main control panel for &kscd;. The function of these buttons +should be familiar to anyone who has ever used a &CD; player.</para> + +<para>The uppermost button in the above diagram toggles between playing and +pausing the &CD;. The left button in the second row stops playing the &CD;. The +right button in the second row ejects the &CD;. The two buttons in the third row +skip forward (right) or backward (left) to the beginning of the next or previous track. +The left button in the bottom row toggles random play order on and off; the right button +in the bottom row toggles looping, so that the &CD; will start +playing again from the beginning when the end of the last audio track is +reached.</para> +</sect2> + + +<sect2 id="status-display"> +<title>The Status Display</title> + +<screenshot> +<screeninfo>The Status Display</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd3.png" format="PNG"/></imageobject> +<textobject><phrase>The Status Display</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This is the status display. Starting at the top, from right to left, is +the main time display (see below for a discussion of the various possible time +display modes), the status of the &CD-ROM; drive, the total play time of the +audio &CD;, the current volume setting, and the current and maximum track +numbers (curr./max.). The bottommost two lines of text display the artist and +title of the &CD;, and then the title of the track, assuming that appropriate +entries exist in the local or network <acronym>CDDB</acronym> (&CD; Data +Base.)</para> + +<para>Click the time display to toggle between the possible main time display modes. By +default, &kscd; displays the elapsed time of the current track, if the &CD; is +playing, or either ––:–– or 00:00 if the &CD; is not playing. +Clicking the display toggles in sequence between remaining track time, total +elapsed time, and total remaining time.</para> +</sect2> + +<sect2 id="configuration-button"> +<title>The <guibutton>Configuration</guibutton> button</title> + +<screenshot> +<screeninfo>The Extras button</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd5.png" format="PNG"/></imageobject> +<textobject><phrase>The Extras button</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This button brings up a menu with a number of options. You can choose to open the &kscd; +configuration panel or configure keyboard shortcuts. These allow you to +configure &kscd; to work exactly to your tastes. See <link linkend="configuring-kscd">the configuring &kscd;</link> section, for details +about configuring &kscd;</para> +<para>The menu provides several tools to help you search for information about the artist on the +Internet. You can find out about performance dates, purchase information, and +other information by pressing this button and choosing the appropriate option in +the popup menu that appears.</para> +<para>This menu also allows you to open this help document, report bugs, learn more +about &kscd; and &kde; and to quit &kscd;.</para> +</sect2> + +<sect2 id="cddb-button"> +<title>The <guibutton>CDDB</guibutton> button</title> + +<screenshot> +<screeninfo>The <acronym>CDDB</acronym> button</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd6.png" format="PNG"/></imageobject> +<textobject><phrase>The <acronym>CDDB</acronym> button</phrase></textobject> +</mediaobject> +</screenshot> + +<para> This button opens the <acronym>CDDB</acronym> (Compact Disc Data Base) entry +editor panel. </para> + +<para>The <acronym>CDDB</acronym> can identify your &CD; and often download a +list of tracks for that &CD; or load it from the filesystem. See the <link +linkend="cddb-editor">&CD; Database Editor</link> section for more details about +using this tool.</para> +</sect2> + + + + +<sect2> +<title>The Volume slider</title> + +<screenshot> +<screeninfo>The Volume slider</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd9.png" format="PNG"/></imageobject> +<textobject><phrase>The Volume slider</phrase></textobject> +</mediaobject> +</screenshot> + +<para> This slider controls the volume of the audio output +of the &CD;. Moving it to the right makes the music louder, left makes it quieter. If you are playing your &CD; through your sound card, +the sound card mixer will affect the playback volume as well.</para> +</sect2> + + +<sect2> +<title>The track selector</title> + +<screenshot> +<screeninfo>The track selector</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd11.png" format="PNG"/></imageobject> +<textobject><phrase>The Track selector</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This combo box shows you the current track number, the name of the track and the time (in minutes and seconds). You can use this drop down box to directly select +any track on the &CD;. </para> +</sect2> + +</sect1> +</chapter> + +<chapter id="configuring-kscd"> +<title>Configuring &kscd;</title> +<sect1 id="configuration-intro"> +<title>The primary configuration window</title> + +<para>You configure &kscd; by clicking on the <guibutton>Extras</guibutton> button. This will bring up a menu, select +<guilabel>Configure &kscd;...</guilabel>. This will open a new window.</para> +<para>The primary configuration window for &kscd; is divided into two +major sections. </para> + +<itemizedlist> +<listitem><para><link linkend="kscd-options-tab"><guilabel>CD +Player</guilabel></link> to determine the look and behavior of &kscd;.</para></listitem> +<listitem><para><guilabel>CDDB</guilabel> which is used to configure the CDDB lookup features of &kscd;.</para></listitem> +</itemizedlist> + +<para>You can switch between these two sections using the icons on the left side of the dialog.</para> +</sect1> + +<sect1 id="kscd-options-tab"> +<title>The <guilabel>CD Player</guilabel> dialog</title> + +<screenshot> +<screeninfo>The <guilabel>CD Player</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd12.png" format="PNG"/></imageobject> +<textobject><phrase>The <guilabel>KSCD Configuration</guilabel> dialog</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The <guilabel>LCD font:</guilabel> text box lists the currently selected font to display all information in the &kscd; status display. To change the font, click the <guibutton>Choose...</guibutton> button.</para> + +<para>The <guilabel>LCD color:</guilabel> and <guilabel>Background +color:</guilabel> fields show the color selected for the foreground and +background of the status display. Press the color bars to change +these colors.</para> + + +<!-- +<para>The <guilabel>Unix mail command</guilabel> field shows the +command used to send new <acronym>CDDB</acronym> entries to the +database. The default value is <userinput><command>mail</command> +<option>-s <replaceable>%s</replaceable></option></userinput>. You +will need to make sure this command will actually send mail to +non-local systems if you want to submit <acronym>CDDB</acronym> +entries, especially if you access the Internet through a dial-up +connection. Check the documentation for your &Linux; distribution for +details. Some Linux distributions that use sendmail to deliver email +require only that you enter your mail host into the +<option>"Smart" relay host</option> field in +<filename>/etc/sendmail.cf</filename>. In addition, the +<acronym>CDDB</acronym> site will want to be able to mail you back; it +may therefore also be necessary to edit +<filename>/etc/sendmail.cf</filename> to ensure that the return +address on the submission is valid. Your mileage is likely to vary. If +all else fails, use <link linkend="smtp-options">SMTP</link> +instead.</para> + +<para>The <guilabel>WWW-Browser</guilabel> section lets you choose which web +browser to use to access the web sites in the <link linkend="information-button">information button</link> menus. You can choose +either &konqueror; or a custom browser with the radio buttons. By default, the +<guilabel>Use Custom Browser</guilabel> field contains +<userinput><command>kfmclient</command> +<option><replaceable>openURL %s</replaceable></option></userinput>.</para> +--> + +<para>Placing a mark in the checkbox labeled <guilabel>Show icon in system tray</guilabel> causes a &kscd; control to +appear in the &kicker; panel.</para> + +<para>Placing a mark in the checkbox labeled <guilabel>Show track announcement</guilabel> causes a small information window to appear on +top of the kicker window each time the &CD; track changes. This window will automatically disappear in 5 seconds.</para> + +<screenshot> +<screeninfo>Sample track announcement</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscdannounc.png" format="PNG"/></imageobject> +<textobject><phrase>Sample track announcement</phrase></textobject> +</mediaobject> +</screenshot> + + +<para>Set the <guilabel>Skip interval</guilabel> box to the desired number of +seconds to move ahead or behind when the <guibutton>forward skip</guibutton> +or <guibutton>reverse skip</guibutton> buttons in the Control Panel are pressed.</para> + +<para><guilabel>Autoplay when CD inserted</guilabel> causes &kscd; to start playing the &CD; +when the tray is closed, with no need to press the +<guibutton>Play</guibutton> button.</para> + +<para><guilabel>Eject CD when finished playing</guilabel> causes the +&CD; to be automatically ejected when playback ends.</para> + +<para><guilabel>Stop playing CD on exit</guilabel> causes &CD; playback to stop +when &kscd; is closed.</para> + +<para>The <guilabel>CD-ROM Device</guilabel> field contains the name +of the &CD-ROM; device to be used to play audio &CD;s. The default +value is <filename>/dev/cdrom</filename>. The permissions on this +device must be set to allow opening this device read-only. Changing +the permissions on this device file will in almost all cases require +superuser privileges and can be done from the command line, or in the +Super User Mode of &konqueror;.</para> + +<note><para>Before we discuss the options that follow, it is important to understand that there are two +ways that personal computers can play a &CD;.</para> + +<para>The first method (which &kscd; refers to as direct digital playback), is performed by reading the digital data from the +&CD; using Digital Audio Extraction (DAE). This data is sent to your machines CPU which converts the digital data to sound. This method requires +a &CD; drive that is capable of DAE (most new drives are) and it requires some CPU processing time to generate the sounds you hear.</para> + +<para>The second method uses the internal circuitry available on most &CD; drives to read the data and generate the sounds you will hear +without using your computers CPU. This data is transmitted by a dedicated cable directly to the sound card in your computer. This method requires +less CPU proccessing time, but it does require that the dedicated cable be connected inside your computer. Not all computers have this connection.</para></note> + +<para>The checkbox labeled <guilabel>Use direct digital playback</guilabel> determines which method &kscd; uses to read the audio tracts. If there is a mark in the checkbox, the first method is used. If there is no mark in the checkbox, the second method is utilized.</para> + +<para>If you have selected direct digital playback, a dropdown box labeled <guilabel>Select audio backend:</guilabel> will let you select which +sound backend the digital information should be sent to. The contents of the dropdown box will vary depending on your system. +Most users should select <guilabel>arts</guilabel>. You can also select the device the audio backend uses by entering the device location in +the text box labeled <guilabel>Select audio device:</guilabel>. A full discussion of audio devices and audio backends is beyond the scope of this manual.</para> + +<para>If a mark is placed in the checkbox labeled <guilabel>Allow encoding selection</guilabel>, you can select the text encoding for the results of a CDDB request.</para> +<tip><para>The standard describes CDDB results as being strictly Latin 1. If you are not having problems with your CDDB information, leave this box unchecked.</para></tip> + + +<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents +page. The <guibutton>Defaults</guibutton> button restores the default values of all entries in this dialog; <guibutton>OK</guibutton> saves the current settings and exits; +<guibutton>Apply</guibutton> saves the current settings without exiting; +<guibutton>Cancel</guibutton> exits without saving. </para> +</sect1> + +<sect1 id="freedb-tab"> +<title>The <guilabel>freedb Lookup</guilabel> tab</title> +<screenshot> +<screeninfo>The <guilabel>freedb Lookup</guilabel> tab of the configuration dialog</screeninfo> +<mediaobject> +<imageobject> <imagedata fileref="kscd14.png" format="PNG"/> </imageobject> +<textobject><phrase>The <guilabel>freedb Lookup</guilabel> tab of the configuration +dialog</phrase></textobject> +</mediaobject> +</screenshot> + +<para> The <guilabel>freedb Lookup</guilabel> tab sets up the <acronym>CDDB</acronym> functions +of &kscd;.</para> + +<para>The <guilabel>Mode</guilabel> option determines how <acronym>CDDB</acronym> lookups +are performed. Setting <guilabel>Cache only</guilabel> means that only information already +on your computer will be used. <guilabel>Cache and remote</guilabel> will look up +information you do not already have while <guilabel>Remote only</guilabel> looks up +every disc over the Internet.</para> + + +<para>The <guilabel>CDDB Server:</guilabel> section determines which CDDB mirror site is used by &kscd; to +get album information. You can enter a server name, port number and protocol using the text boxes and drop +down boxes or you can click the <guibutton>Show Mirror List</guibutton> button. Clicking this button will +open a new window with a list of CDDB mirrors and their locations. Simply select the server you want from +the list and click <guibutton>OK</guibutton>.</para> + +<para>The section labeled <guilabel>Cache locations</guilabel> lets you determine where &kscd; saves CDDB information +on your computer. To add a folder, enter the folder location in the text box at the top of the section and click +<guibutton>Add</guibutton>. You can also select a +folder by clicking on the blue file folder to the right of the text box. To delete a folder, click on the folder name +once with the &LMB; and click <guibutton>Remove</guibutton>. You can change the order that &kscd; searches the folders by +clicking on the folder name and clicking on the <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons.</para> + +<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents +page. The <guibutton>Defaults</guibutton> button restores the default values of all entries in this dialog; <guibutton>OK</guibutton> saves the current settings and exits; +<guibutton>Apply</guibutton> saves the current settings without exiting; +<guibutton>Cancel</guibutton> exits without saving. </para> + +</sect1> + +<sect1 id="smtp-options"> +<title>The <guilabel>freedb Submit</guilabel> tab</title> + +<screenshot> +<screeninfo>The freedb Submit tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd16.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>The freedb Submit tab sets up connection to a mail +server or a web server to submit new <acronym>CDDB</acronym> entries. This is useful +if you do not have your own system configured as a server. </para> + +<para>If you plan to submit a CDDB entry, first you must decide between submitting between HTTP +and submitting the entry as an email (via SMTP). </para> + +<tip><para>It is simpler to submit new entries using &HTTP;. Some firewalls block this traffic. If your +firewall prevents you from sending new entries using &HTTP;, you can use SMTP.</para></tip> + +<para>First select either <guilabel>&HTTP;</guilabel> or <guilabel>SMTP (Email)</guilabel> to determine which +protocol to use.</para> + +<sect2 id="http-options"> +<title>Using &HTTP; to send CDDB information</title> +<para>You can enter a server name or port number in the text boxes provided. If +you want to send this information to the international servers, you do not need to +change anything.</para> +</sect2> + +<sect2 id="smtp2-options"> +<title>Using SMTP (Email) to send CDDB information</title> +<para>To prepare to submit information using email, enter your email address in the +textbox labeled <guilabel>Reply-To:</guilabel>, your email server in the textbox +labeled <guilabel>SMTP-server:</guilabel> and select the port number in the dropdown box +labeled <guilabel>Port:</guilabel>.</para> +<para>If you need to use a password to send email using the email server, place a mark in the +checkbox labeled <guilabel>Server needs authentication</guilabel> and enter your +username in the textbox labeled <guilabel>Username:</guilabel>.</para> + +<para>The <guibutton>Help</guibutton> button opens the &kscd; help contents +page. The <guibutton>Defaults</guibutton> button restores the default values of all entries in this dialog; <guibutton>OK</guibutton> saves the current settings and exits; +<guibutton>Apply</guibutton> saves the current settings without exiting; +<guibutton>Cancel</guibutton> exits without saving. </para> +</sect2> +</sect1> + + +</chapter> + +<chapter id="cddb-editor"> +<title>The <guilabel>CD Database Editor</guilabel></title> + +<screenshot> +<screeninfo>The &CD; Database Editor</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd13.png" format="PNG"/></imageobject> +<textobject><phrase>The &CD; Database Editor</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The &CD; Database Editor allows you to modify, download, save, annotate, +and upload <link linkend="cddb-support"><acronym>CDDB</acronym> (Compact Disc +Data Base)</link> entries.</para> + +<para>If there is an entry in your local <acronym>CDDB</acronym> tree +(see the <link linkend="freedb-tab">CDDB subsection</link> in the +Configuration chapter) for the &CD; in your &CD-ROM; drive, or if the +disc could be found in the freedb, you will see the name of the artist +and the title of the &CD; in the <guilabel>Artist:</guilabel> and +<guilabel>Title</guilabel> fields and a list of tracks with song +titles in the <interface>Tracks</interface> selection box. Otherwise, +you will see a list of tracks and play times without titles.</para> + +<para>You can make an annotation for the entire disc with the +<guibutton>Comment</guibutton> button under the +<guilabel>Title</guilabel> field, or for a selected track in the +<guilabel>Tracks</guilabel> selection box with the adjacent +<guibutton>Comment</guibutton> button. If you select a track in the +<guilabel>Tracks</guilabel> selection box, the title, if present, will +appear in the <guilabel>Title</guilabel> field below. You can type a +title for the track in the box, or edit the entry to suit your +needs. Press the <keycap>Return</keycap> key on your keyboard, and the +text will appear in the proper line in the selection box.</para> + +<para>Once all tracks have been given titles and the +<guilabel>Artist:</guilabel> and <guilabel>Title</guilabel> fields have +been filled out, you can press the <guibutton>Upload</guibutton> +button to send your submission by e-mail to freedb.</para> + +<para>You will be prompted to select a category for the +submission. The <guilabel>Disc ID</guilabel> section displays the 32 +bit <acronym>ID</acronym> code used by freedb to identify a compact +disc. Above the <acronym>ID</acronym> code is the category of the +<guilabel>freedb</guilabel> entry. These categories correspond to the +subfolders tree of the folder chosen in the <guilabel>freedb +Base Folder:</guilabel> in the <link +linkend="freedb-tab"><guilabel>freedb</guilabel> tab</link> of the &kscd; +Configuration window.</para> + +<para>The <guilabel>Length:</guilabel> display shows the total play time of +the &CD;.</para> + +<para>Press the <guibutton>Fetch Info</guibutton> button to download +<acronym>CDDB</acronym> data. +Press the <guibutton>OK</guibutton> button to save your changes locally. +The <guibutton>Cancel</guibutton> button closes the &CD; +Database Editor without saving.</para> + +</chapter> + +<chapter id="using-kscd-in-the-panel"> +<title>Using &kscd; in the &kde; Panel</title> + +<screenshot> +<screeninfo>Using &kscd; in the &kde; Panel</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd18.png" format="PNG"/></imageobject> +<textobject><phrase>Using &kscd; in the &kde; Panel</phrase></textobject> +</mediaobject> +</screenshot> + +<para>When the <guilabel>Show icon in system tray</guilabel> box is checked, a +small &kscd; applet is also displayed in the &kicker;. Unlike the main &kscd; window, this applet is available on +any desktop. <mousebutton>Right</mousebutton> click on the applet to pop up a +menu to control &CD; playback. A <mousebutton>left</mousebutton> click on the +applet hides the main &kscd; window. If the main window is hidden, a second +<mousebutton>left</mousebutton> click on the applet restores it. </para> + +<note><para>To be precise, the applet is displayed in the <application>system +tray</application> in the panel. If no applet appears when &kscd; is minimized, +you may have removed the tray. To add it, <mousebutton>right</mousebutton> click +on an empty spot on the panel and select <menuchoice><guisubmenu>Add</guisubmenu> +<guisubmenu>Applet</guisubmenu> <guimenuitem>System Tray</guimenuitem> +</menuchoice></para></note> + +</chapter> + +<chapter id="cddb-support"> +<title><acronym>CDDB</acronym> Support</title> + +<para>freedb is a distributed network database accessible +over the Internet that contains information about most audio &CD;s in +circulation. If you have Internet access, you will likely never have to manually +enter track information for your &CD;s if you have this set up properly. See +<link linkend="freedb-tab">The freedb Tab</link> subsection in the configuring +&kscd; chapter for detailed instructions on how to configure this service, and +the <link linkend="cddb-editor">The CD Database Editor</link> section for +instructions on how to edit <acronym>CDDB</acronym> entries.</para> + +<para>Use of the <acronym>CDDB</acronym> is free. Submissions from users are +encouraged.</para> + +<para>When preparing entries for the <acronym>CDDB</acronym>, please keep the +following points in mind:</para> + +<itemizedlist> +<listitem><para>Use <quote>standard</quote> latin characters in the entries. Some +special characters are supported, but Cyrillic or Greek alphabet submissions, +for example, cannot be accepted.</para></listitem> +<listitem><para>Use only one <keysym>/</keysym> character in the +<guilabel>Disc Artist / Title</guilabel> field in the &CD; Database +Editor.</para> + +<para>For classical &CD;s, it is standard practice to put the composer's name in +the Artist section (before the slash) and the performer's name in the Title +section (after the slash).</para></listitem> +<listitem><para>If you send an entry that already exists in the database, any +additional information you provide may be added to the existing entry.</para> +</listitem> +</itemizedlist> + +<para>By default, &kscd; installs the standard <acronym>CDDB</acronym> +categories in <filename class="directory">$KDEDIR/share/apps/kscd/cddb</filename>. You can create as +many category subfolders as you like. However, when uploading, only the +official <acronym>CDDB</acronym> categories are displayed. The default upload +address is <email>freedb-submit@freedb.org</email>. For more information about +<abbrev>freedb</abbrev> visit the <abbrev>freedb</abbrev> homepage.</para> + +<para>The local <acronym>CDDB</acronym> entry for a particular &CD; is stored in +the file <filename><replaceable>category name</replaceable>/<replaceable>disc +ID</replaceable></filename> under the <acronym>CDDB</acronym> Base +Folder. These files can be edited with any text editor if you have nothing +better to do with your spare time.</para> + +</chapter> + +<chapter id="troubleshooting"> +<title>Troubleshooting the CD player</title> + +<para>This section of the manual provides a step by step guide to troubleshooting your CD drive if the CD player will not play an audio &CD;</para> + +<sect1 id="ts-begin"> +<title>Begin troubleshooting</title> +<para>To begin, place an audio CD in your CD drive. Close the CD drive door and press play on the &kscd; window. Watch the CD drive on your computer and select the link below that best describes the problem.</para> +<para>When I pressed <guilabel>Play</guilabel>:</para> +<itemizedlist> +<listitem><para><link linkend="ts-errorbox">An error box appeared</link></para></listitem> +<listitem><para><link linkend="ts-playing">No error box appeared</link></para></listitem> +</itemizedlist> +</sect1> +<sect1 id="ts-playing"> +<title>I did not get an error box, but no sound is coming out of my speakers</title> +<para>First, we will check to make sure the volume is turned up in &kscd;.</para> +<para>Near the upper right corner of the &kscd; window, locate the volume slider. The volume slider looks like this:</para> +<screenshot> +<screeninfo>The Volume slider</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd9.png" format="PNG"/></imageobject> +<textobject><phrase>The Volume slider</phrase></textobject> +</mediaobject> +</screenshot> +<para>Click once on the vertical yellow bar and drag the bar all the way to the right end of the slider.</para> +<para>If you can hear music now, the problem is solved. If you still can not hear the music, click +<link linkend="ts-kmixlevels">here</link> to continue.</para> +</sect1> +<sect1 id="ts-kmixlevels"> +<title>Determining if the mixer volume levels are up</title> +<para>The next step is to determine if &kmix; volume levels are appropriate.</para> +<note><para>&kmix; is a sound mixer panel that is included in &kde;. This mixer allows you to adjust the relative volume levels of many sound components.</para></note> +<para>To start &kmix;, select +<menuchoice><guimenu>K-Button</guimenu><guimenuitem>Multimedia</guimenuitem> +<guimenuitem>&kmix;</guimenuitem></menuchoice>.</para> +<para>Once &kmix; has started, you will be presented with a new window with a number of volume sliders. Depending on the configuration, the sliders may have lables, or the labels may be hidden. If you do not see any labels for the sliders, you should make the labels visible before continuing. To make the labels visible, select +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kmix;...</guimenuitem></menuchoice> from the &kmix; window. This will open a small window with a few check boxes. To +turn the labels on, place a mark in the checkbox labeld <guilabel>Show labels</guilabel> and click <guibutton>OK</guibutton>.</para> +<para>Each slider controls the volume of a different audio device. There are two parts to each device that may need to be altered. If you look at a slider, there is a green +light above each slider. If you click on this light you can toggle between bright green and dark green. If the light is dark green, that audio device is muted and will not produce any sound. If the light is light green, the device is not muted. Once you have verified that the device is not muted, you increase the volume of the device by draging the yellow bar up the slider. The volume of an audio device is decreased by dragging the yellow bar down the slider.</para> +<note><para>Some sliders will have a red light as well. This light is not important for playback of compact discs so you can ignore them for now.</para></note> +<para>Click on the tab labeled <guilabel>Output</guilabel>.</para> +<para>Please make sure the sliders are not muted (bright green light) and that the yellow bar is all the way at the top of the slider for the following audio devices:</para> +<itemizedlist> +<listitem><para><guilabel>Master</guilabel></para></listitem> +<listitem><para><guilabel>Master Mono</guilabel></para></listitem> +<listitem><para><guilabel>PC Speaker</guilabel></para></listitem> +<listitem><para><guilabel>PCM</guilabel></para></listitem> +</itemizedlist> + +<para>If you still do not hear the &CD;, click on the tab labeled <guilabel>Input</guilabel></para> +<para>Now make sure the slider labeled <guilabel>CD</guilabel> is not muted (bright green light) and that the yellow bar is all the way at the top of the slider.</para> +<para>If you can hear the &CD; now, you can stop troubleshooting. If not, click <link linkend="ts-othersounds">here</link> to continue</para> +</sect1> +<sect1 id="ts-othersounds"> +<title>Determine if other sounds are audible on my computer</title> +<para>In this section, we are going to test to see if other types of sounds are audible on your computer. We will do this by playing a sound over the speakers that is stored on your hard drive. </para> +<para>First we must locate an appropriate test file. This will be done using the command line.</para> +<para>Select <menuchoice><guimenu>K-Button</guimenu><guimenuitem>System</guimenuitem> +<guimenuitem>&konsole;</guimenuitem></menuchoice>. A new window will appear with a command prompt. At the prompt type:</para> +<para><screen><prompt>$</prompt> <userinput><command>locate -n1 KDE_Window_Open.wav</command></userinput></screen></para> +<para>When you press return, there will be a pause, and a single line with a file location will be printed below your typed command.</para> +<para><screen><prompt>$</prompt> <userinput><command>locate -n1 KDE_Window_Open.wav</command></userinput> +/usr/local/kde/share/sounds/KDE_Window_Open.wav</screen></para> + +<para>Now you are going to ask &kde; to play this short sound file. Type the text <command>noatun</command> followed by a space. Then copy the full location of the file you just located with the previous command. For example: </para> +<para><screen><prompt>$</prompt> <userinput><command>noatun /usr/local/kde/share/sounds/KDE_Window_Open.wav</command></userinput></screen></para> +<para>If you heard a short sound, <link linkend="ts-othersoundsplay">click here</link>.</para> +<para>If you did not hear a short sound, your sound system is not configured correctly. Click <link linkend="ts-noothersounds">here</link> to proceed.</para> +</sect1> + +<sect1 id="ts-noothersounds"> +<title>The test sound failed to play</title> +<para>So far, we have verified that the volume on &kscd; and all the mixer levels in &kmix; are set correctly. We have also sent a test sound and you could not hear the sound played. This suggests the trouble is not with &kscd; but rather with your sound configuration.</para> +<note><para>Please make sure the &CD; is still playing in your CD drive.</para></note> +<para>First, we need to make sure your speakers are plugged in and that the volume of your speakers is set appropriately. If you are using external speakers, please check the following:</para> +<itemizedlist> +<listitem><para>Please make sure the speakers are connected to your computer appropriatly (see your user manual if necessary).</para></listitem> +<listitem><para>If your speakers require batteries, please replace the batteries with fresh batteries.</para></listitem> +<listitem><para>If your external speakers plug into the wall, please make sure they are plugged in to the socket, the power cord is securly plugged into the back of the speakers and the wall outlet is working.</para></listitem> +<listitem><para>If your speakers have a power button, please make sure the power is turned on.</para></listitem> +<listitem><para>If your speakers have a volume knob, please make sure the volume is turned half way between off and maximum.</para></listitem> +</itemizedlist> + +<para>If your speakers are part of you computers case, please check to see if your speakers have a volume knob. If they do make sure the volume is turned half way between off and maximum.</para> + +<para>If you have checked all of this, you probably need detailed help on getting the sound working on your computer. A full discussion of troubleshooting the sound system is beyond the scope of this manual and the user is referred to other internet sources. Some potential sources of information are:</para> + +<itemizedlist> +<listitem><para><ulink url="http://www.tldp.org/HOWTO/Sound-HOWTO/index.html">Linux Sound HOWTO</ulink>.</para></listitem> +<listitem><para>The website of your distribution will probably have a user forum for asking questions.</para></listitem> +<listitem><para>Post a question to a Usenet newsgroup like comp.os.linux</para></listitem> +<listitem><para>Use a search engine to locate others who have encountered similar problems as you.</para></listitem> +</itemizedlist> +</sect1> + +<sect1 id="ts-othersoundsplay"> +<title>The test sound played, but I can not hear the &CD;</title> +<para>So far, we have verified that the volume on &kscd; and all the mixer levels in &kmix; are set correctly. We have also played a test sound and you were able to hear the sound played. This suggests the trouble is limited to &kscd; or the &CD;.</para> +<para>Check to make sure the &CD; is playable. If this is a new &CD;, put it in another CD player (preferrably not located in a computer) and make sure the &CD; is playable in that device. If it is playable in another device, continue <link linkend="ts-ddpback">here</link>.</para> +</sect1> + +<sect1 id="ts-ddpback"> +<title>Try using direct digital playback</title> +<para>There are two +ways that personal computers can play a &CD;.</para> + +<para>The first method (which &kscd; refers to as direct digital playback), is performed by reading the digital data from the +&CD; using Digital Audio Extraction (DAE). This data is sent to your machines CPU which converts the digital data to sound. This method requires +a &CD; drive that is capable of DAE (most new drives are) and it requires some CPU processing time to generate the sounds you hear.</para> + +<para>The second method uses the internal circuitry available on many &CD; drives to read the data and generate the sounds you will hear +without using your computers CPU. This data is transmitted by a dedicated cable directly to the sound card in your computer. This method requires +less CPU proccessing time, but it does require that the dedicated cable be connected inside your computer. Not all computers have this connection.</para> + +<para>&kscd; defaults to the second method of playback. The next step in troubleshooting your &CD; problems is to enable direct digital playback. To do this begin by clicking on the button labeled <guibutton>Stop</guibutton> on the &kscd; window. This will stop any attempt to play the &CD; for now.</para> + +<para>Now click on the button labeled <guibutton>Extras</guibutton>. This will open a small menu. Select <guilabel>Configure &kscd;...</guilabel>. This will open a new dialog box.</para> +<para>Click the icon labeled <guilabel>CD Player</guilabel> on the left side of the dialog box.</para> +<para>Place a mark in the checkbox labeled <guilabel>Use direct digital playback</guilabel>.</para> +<para>Click <guibutton>OK</guibutton>. </para> +<para>Now click <guibutton>Play</guibutton> in the &kscd; window and see if the &CD; begins to play correctly.</para> + +<para>If you still can not hear the music on the &CD;, your problem requires specific knowledge of your system and the problems you encounter. The reader is referred to many good internet resources for this information. Please consider finding help in one of the following ways:</para> + +<itemizedlist> +<listitem><para>The website of your distribution will probably have a user forum for asking questions.</para></listitem> +<listitem><para>Post a question to a Usenet newsgroup like comp.os.linux or an IRC channel for users of your operating system</para></listitem> +<listitem><para>Use a search engine to locate others who have encountered similar problems as you.</para></listitem> +</itemizedlist> + +</sect1> + + +<sect1 id="ts-errorbox"> +<title>An error box appeared</title> +<para>Probably the most common error boxes seen is this one:</para> +<screenshot> +<screeninfo>Error dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd19.png" format ="PNG"/></imageobject> +<textobject><phrase>Error dialog</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Information about fixing this dialog box is available in the <link linkend="questions-and-answers">Questions and +answers</link> section of this manual.</para> + +<para>If you recieve another error box, you should post the text from the error box on a forum for your distribution or enter this text in a search engine such +as <ulink url="http://www.google.com">Google</ulink>.</para> +</sect1> +</chapter> + +<chapter id="questions-and-answers"> +<title>Questions and answers</title> + +<qandaset> +<qandaentry> +<question><para>I see this dialog when I start &kscd;. What's wrong?</para> +<screenshot> +<screeninfo>Error dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kscd19.png" format ="PNG"/></imageobject> +<textobject><phrase>Error dialog</phrase></textobject> +</mediaobject> +</screenshot> +</question> +<answer><para>This means that &kscd; couldn't open your &CD-ROM; drive. The name of +the device in the <guilabel>&CD-ROM; Device</guilabel>cdrom field of the +<guilabel>Kscd Configuration</guilabel> must actually refer to the block device +associated with your &CD-ROM; drive. This will often be a hardlink to the +appropriate <acronym>IDE</acronym> (<filename>/dev/hdx</filename>) or +<acronym>SCSI</acronym> (<filename>/dev/sdx</filename>) device.</para> + +<para> The device file normally belongs to user root in group root, and does not +allow normal users to open it for reading, writing, or execution directly. This +has <emphasis>nothing</emphasis> to do with the <application>SUID</application> +(Set User <acronym>ID</acronym> programs use the <function>setuid()</function> +function in the standard Un*x library to assume the identity of another user) +<command>mount</command> command, which has no problems with permissions; &kscd; +must be able to get a read-only file descriptor referring to the &CD; device to +control the &CD-ROM; drive and read raw data off the disk.</para> + +<para> If you have the root password, you can fix this quickly and easily. +Become root and type <userinput><command>chmod</command> <option>a+r</option> +<filename><replaceable>/dev/cdrom</replaceable></filename></userinput> to allow +any user on your system to read from <filename>/dev/cdrom</filename>. If your +&CD-ROM; device is called something else, change the permissions on that device +with the same procedure. If you don't have the root password, ask your system +administrator nicely to give you read permission for the &CD-ROM; device.</para> + +<para>See also the chapter on <link linkend="configuring-kscd">configuring KSCD +</link></para></answer> +</qandaentry> + +<qandaentry> +<question><para>I can not get the <acronym>CDDB</acronym> to work. Can I get any +detailed information about what may be going wrong?</para></question> +<answer><para>If you experience trouble with the <acronym>CDDB</acronym> +functionality try to starting &kscd; from the command line with the +<option>-d</option> switch and observe the debug output.</para></answer> +</qandaentry> +</qandaset> +</chapter> + +<chapter id="credits-and-license"> +<title>Credits and licenses</title> + +<para>&kscd; Copyright 1997,1998 &Bernd.Johannes.Wuebben; +&Bernd.Johannes.Wuebben.mail;</para> + +<para>&kscd; contains code from: </para> +<itemizedlist> +<listitem><para><application>workman</application> 1.4 beta 3 Copyright (c) +Steven Grimm <email>koreth@hyperion.com</email></para></listitem> +</itemizedlist> + + +<para>Special thanks to Ti Kan and Steve Scherf, the inventors of the +<acronym>CDDB</acronym> database concept. Visit <ulink +url="http://www.cddb.com/">http://ww.cddb.com</ulink> for more information on +<acronym>CDDB</acronym>.</para> + +<para>A very special thank you also to David White who wrote the original &kscd; +help documention. Great Job David!</para> + +<para>Documentation updated for KDE 2.0, and copyright by &Jonathan.Singer; +&Jonathan.Singer.mail;</para> + +<para>Documentation updated for KDE 3.4, and copyright by &Mike.McBride; +&Mike.McBride.mail;</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="how-to-obtain-kscd"> +<title>How to obtain &kscd;</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>In order to successfully compile &kscd;, you need the latest versions of +the KDE libraries as well as the &Qt; C++ library. All required libraries as +well as &kscd; itself can be found at the &kde; &FTP; site, &kde-ftp;.</para> + +</sect1> + +<sect1 id="compilation-and-installation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +<para>Please inform the current maintainer, Aaron Seigo, at +&Aaron.J.Seigo.mail; of any modification you had to undertake in +order to get &kscd; to compile on your platform.</para> + +</sect1> + +</appendix> + +&documentation.index; +</book> +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> diff --git a/doc/kscd/kscd.png b/doc/kscd/kscd.png Binary files differnew file mode 100644 index 00000000..027c324d --- /dev/null +++ b/doc/kscd/kscd.png diff --git a/doc/kscd/kscd11.png b/doc/kscd/kscd11.png Binary files differnew file mode 100644 index 00000000..d1902fda --- /dev/null +++ b/doc/kscd/kscd11.png diff --git a/doc/kscd/kscd12.png b/doc/kscd/kscd12.png Binary files differnew file mode 100644 index 00000000..68a9328b --- /dev/null +++ b/doc/kscd/kscd12.png diff --git a/doc/kscd/kscd13.png b/doc/kscd/kscd13.png Binary files differnew file mode 100644 index 00000000..c957e1f9 --- /dev/null +++ b/doc/kscd/kscd13.png diff --git a/doc/kscd/kscd14.png b/doc/kscd/kscd14.png Binary files differnew file mode 100644 index 00000000..cbc30004 --- /dev/null +++ b/doc/kscd/kscd14.png diff --git a/doc/kscd/kscd16.png b/doc/kscd/kscd16.png Binary files differnew file mode 100644 index 00000000..fc66d57a --- /dev/null +++ b/doc/kscd/kscd16.png diff --git a/doc/kscd/kscd18.png b/doc/kscd/kscd18.png Binary files differnew file mode 100644 index 00000000..cd33de29 --- /dev/null +++ b/doc/kscd/kscd18.png diff --git a/doc/kscd/kscd19.png b/doc/kscd/kscd19.png Binary files differnew file mode 100644 index 00000000..24b77794 --- /dev/null +++ b/doc/kscd/kscd19.png diff --git a/doc/kscd/kscd2.png b/doc/kscd/kscd2.png Binary files differnew file mode 100644 index 00000000..f9d724ab --- /dev/null +++ b/doc/kscd/kscd2.png diff --git a/doc/kscd/kscd3.png b/doc/kscd/kscd3.png Binary files differnew file mode 100644 index 00000000..3b1dabba --- /dev/null +++ b/doc/kscd/kscd3.png diff --git a/doc/kscd/kscd5.png b/doc/kscd/kscd5.png Binary files differnew file mode 100644 index 00000000..2e01ef69 --- /dev/null +++ b/doc/kscd/kscd5.png diff --git a/doc/kscd/kscd6.png b/doc/kscd/kscd6.png Binary files differnew file mode 100644 index 00000000..8c114f10 --- /dev/null +++ b/doc/kscd/kscd6.png diff --git a/doc/kscd/kscd9.png b/doc/kscd/kscd9.png Binary files differnew file mode 100644 index 00000000..4a199f35 --- /dev/null +++ b/doc/kscd/kscd9.png diff --git a/doc/kscd/kscdannounc.png b/doc/kscd/kscdannounc.png Binary files differnew file mode 100644 index 00000000..ff51f096 --- /dev/null +++ b/doc/kscd/kscdannounc.png diff --git a/doc/noatun/Makefile.am b/doc/noatun/Makefile.am new file mode 100644 index 00000000..171f575c --- /dev/null +++ b/doc/noatun/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/noatun/index.docbook b/doc/noatun/index.docbook new file mode 100644 index 00000000..7a6bd2b7 --- /dev/null +++ b/doc/noatun/index.docbook @@ -0,0 +1,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; — 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>"kbps"</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—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> + |
