<?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>
<holder>Arnold Krille</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>

<date>2002-08-20</date>
<releaseinfo>0.01.00</releaseinfo>

<abstract>
<para>&krec; is a  recording frontend for &arts;. It can be used to
record single files or whole recording sessions. Some dynamic effects
are implemented as well as the possibility to play out what you are
recording (as long as you are not recording what you are hearing).
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdemultimedia</keyword>
<keyword>KRec</keyword>
<keyword>aRts</keyword>
<keyword>recording</keyword>
<keyword>frontend</keyword>
</keywordset>

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

<sect1 id="why-krec">
<title>Why I wrote &krec;</title>

<para>
After some working with &arts; I realized that there is no recording
frontend 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 a file.
</para>
<para>At the moment it only writes raw files, which are the same as normal Wavefiles but without
the wav header (<application>sox</application> can add this header fo you).
</para>
</sect1>

</chapter>

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

<para>This chapter describes the usage of &krec;. There are several
ways of using &krec; so I created some <quote>HOWTO</quote>-like
sections describing this possibilities of usage. Just read the first
paragraph of each and decide what you need to read. Or read everything
and learn about the fantastic possibilities of &krec;.</para>

<screenshot>
<screeninfo>Here's a screenshot of &krec;</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="krec-hicolor.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Here is a screenshot of &krec; right after it started.</phrase>
</textobject>
</mediaobject>
</screenshot>

<sect1 id="simple-usage">
<title>Recording of a simple file</title>

<para>
If you hear something on the radio you want to record (and your radio is 
plugged into your soundcard) there is a (relatively) fast way to record.
</para>

<orderedlist>
<listitem>
<para>First you have to select the recording source in your soundcard.
You need your favorite mixer (&kmix;), where you should select the
source you need for recording. You also need to configure the
&arts; server for full-duplex (and your soundcard and drivers should
support this too). If you need to restart &arts; you should also
restart &krec; </para>
</listitem>
<listitem>
<para>Then you need to open &arts; Control and its Audio Manager.  It
shows two new Items: &krec;::In and &krec;::Out, the latter is used
for playback and play-thru and is irrelevant here. The former needs
our attention; it should be connected with the
<emphasis>in_soundcard</emphasis> bus. If you can't select it you
probably misconfigured something (no full-duplex or something like
this).</para>
</listitem>
<listitem>
<para>If everything worked you now should see something moving inside 
&krec; &mdash; the VU-Meter showing how loud your recording is. For good 
recordings without clipping it should be yellow to orange but not red. The 
slider right of the VU-Meter controls the volume.</para>
</listitem>
<listitem>
<para>Now you need a file to record to. Use
<menuchoice><guimenu>File</guimenu><guimenuitem>New
File</guimenuitem></menuchoice> or the toolbar symbol to create
it. After that you need to tell &krec; to record to this file. That is
done in the context menu of the file item.</para>
</listitem>
<listitem>
<para>Now you are able to start recording. Use the big red button in
the toolbar or <guimenu>Play</guimenu>
<guimenuitem>Record</guimenuitem> or simply press
<keycap>R</keycap>. To stop use the stop button or the entry in the
<guimenu>Play</guimenu> menu (or the key
<keycap>S</keycap>).</para>
</listitem>
</orderedlist>

<para>Okay, it is not as fast as pressing the record button on your
tapedeck but &krec; has some more features than your tapedeck, believe
me.</para>

<tip>
<para>You may want to record other things. For testing you can take the output 
signal of &noatun;: Set &krec;::In to the <emphasis>out_soundcard</emphasis> 
(or any other bus you let &noatun; play to). This even works if you don't 
have a full-duplex enabled &arts;.</para>
</tip>
</sect1>

<sect1 id="advanced-usage">
<title>Recording several files</title>

<para>
For this section we assume you want to record several small or bigger pieces 
into several files. For example, you want to record scenes for a radio play or 
something like that. (That was the reason I wrote &krec;.)
</para>

<para>
I assume you have worked with &arts; before and know a bit about the topic 
<quote>Audiorecording</quote>. Your mic, or whatever you want to record from, should be 
plugged into your computer and you should know what to configure (outside 
&krec;) to get the input signal recorded.
</para>

<para>
This <quote>walk-through</quote> uses a radio play as an example. We 
have to decide wether we want all the recordings to be named differently or we 
want to name some or all recordings by the same name, differing only in a 
number. For the first, follow the instructions in <xref linkend="simple-usage"/> 
and keep in mind that you can open several files at the same time and then 
choose which one to record to. The second is described here...
</para>

<orderedlist>
<listitem><para>Before we start be sure you have everything set up correctly, particularly that 
you are really recording what you want. You can confirm that everything is 
alright if the VU-Meter in &krec; is moving. If you are not recording from 
<emphasis>out_soundcard</emphasis> you can select <guimenu>Play</guimenu> 
<guimenuitem>Play Through</guimenuitem> to get the recorded signal put through 
to your soundcard output, which I would do rather then listening to it via your 
soundcard mixer because you can hear if it is too loud or too 
quiet.</para></listitem>
<listitem><para>For several files with the same name you need a session. 
<guimenu>File</guimenu> <guimenuitem>New Session</guimenuitem> should do it. 
Select the path and enter a filename which gets expanded with the number and the 
postfix of the recording.</para></listitem>
<listitem><para>You still need files to record to but this time you create them 
by selecting <guimenuitem>New File</guimenuitem> from the context menu. You can 
create as many files as you want/need.</para></listitem>
<listitem><para>The rest is simple: Select the file you want to record to and 
then record...</para></listitem>
</orderedlist>

<note><para>
A session is not another MIME type, or even a file. It is just an 
internal thing to organize the numbering. So you can not later re-open a session 
and continue recording to new files...
</para></note>
</sect1>

<sect1 id="more-usage">
<title>More tips and comments on usage</title>

<para>There are some more things to say and some more elements to
explain.</para>

<sect2 id="usage-play-through">
<title>Using Play-Through</title>

<para>For those of you who want to hear what they are recording there
is a very useful <quote>Play-Through</quote> option. It is found in
the menu <guimenu>Play</guimenu>. I advise using it as much as
possible especially if you do other things like using the compressor
or other effects as well. See <xref linkend="internals"/> for details
on the connections.</para>

<caution>
<para>Be sure to not build a feedback loop while recording from 
<emphasis>out_soundcard</emphasis> and activating <quote>Play-Through</quote>. 
Such a loop is to much for poor &arts; and it slows your system way, way 
down! You might kill &arts;...</para>
</caution>

</sect2>

<sect2 id="using-compressor">
<title>Using 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 when recording 
speech. To correct this you can use the compressor. It simply reduces all sound 
that is over the given threshold by the factor given in ratio. As this reduces 
the loudness there is a output potentiometer to expand (or reduce) the sound. Attack and 
Release 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 <quote>Play 
Through</quote> enabled and you will hear the difference.</para></tip>
</sect2>

<sect2 id="usage-switching-file">
<title>Switching between several files</title>

<para>Like you can open several files for recording, you also can
switch between them.  This can be done not only after you stop
recording, but also while you are recording. Note that some
data packets can be lost while doing this. How much sound information
this is depends on the size of your Audio Buffer configured in the
&kcontrol; for &arts;. It shouldn't be that much but if you play the
files directly one after the other (for example with <command>artscat
file*.raw</command>) you can hear some small
<quote>jumps</quote>.</para>
</sect2>

</sect1>
 
<sect1 id="internals">
<title>Internals</title>

<para>
Let me say something about the sound connection in &krec;.
</para>
<para>
There are some items needed for recording with &arts;: a synth_AMAN_RECORD, a 
AudioToByteStream converter and a ByteStreamReceiver. The first two are build 
inside the &arts; server. The latter is inside the application. But that's only 
the basics. If you want to listen to the files you need a ByteStreamSender 
inside your application and a ByteStreamToAudio converter and a synth_AMAN_PLAY 
inside the server.
</para>
<para>
What about the effects? Between the AMAN_RECORD and the AutioToByteStream I 
plugged a StereoEffectStack into which I put the compressor 
(synth_STEREO_COMPRESSOR) and a volume control (StereoVolumeControl).
</para>
<para>
If you enable <quote>Play Through</quote> the effects stack also gets connected 
with the AMAN_PLAY. So this is all inside the &arts; server...
</para>
</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="krec-mainwindow">
<title>The main &krec; window</title>

<sect2>
<title>The <guimenu>File</guimenu> Menu</title>

<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut> <keycombo action="simul"><keycap>N</keycap></keycombo> </shortcut>
<guimenu>File</guimenu> <guimenuitem>New File</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new single file for recording into one 
file</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut> <keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> 
</shortcut>
<guimenu>File</guimenu> <guimenuitem>New Session</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new session for multiple 
recordings</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</action> &krec;</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2>
<title>The <guimenu>Play</guimenu> Menu</title>

<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut> <keycombo action="simul"><keycap>P</keycap></keycombo> </shortcut>
<guimenu>Play</guimenu> <guimenuitem>Play</guimenuitem>
</menuchoice></term>
<listitem><para><action>Plays the file selected for 
playback.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut> <keycombo action="simul"><keycap>R</keycap></keycombo> </shortcut>
<guimenu>Play</guimenu> <guimenuitem>Record</guimenuitem>
</menuchoice></term>
<listitem><para><action>Starts the recording into the selected 
file.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut> <keycombo action="simul"><keycap>S</keycap></keycombo> </shortcut>
<guimenu>Play</guimenu> <guimenuitem>Stop</guimenuitem>
</menuchoice></term>
<listitem><para><action>Stops the recording.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut> <keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> 
</shortcut>
<guimenu>Play</guimenu> <guimenuitem>Play thru</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Connects the input with the output to let you hear what you are 
recording.</action> (&krec;::In and &krec;::Out in the audio manager of 
&arts; control)</para>
<caution><para>Never use this while recording what you hear (from 
out_soundcard). This gives feedback which &arts; is not able to handle. (It does 
not ieck because &arts; is faster then feedback from your box to the 
microphone.)</para></caution>
</listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>

<para>
<variablelist>

<varlistentry>
<term><menuchoice>

<guimenu>Settings</guimenu> <guimenuitem>Show Startup Window</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles whether the startup window with the 
quick tutorial is shown.</action></para></listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2>
<title>The <guimenu>Help</guimenu> Menu</title>

&help.menu.documentation;

</sect2>

</sect1>

<sect1 id="startupwindow">
<title>The startup window</title>

<para>
This startup window is almost the same as the &ktip; dialog.
</para>
</sect1>

</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question>
<para>I recorded some files with &krec;, but I can not play the files with my 
favorite player?</para>
</question>
<answer>
<para>&krec; (currently) records only into raw files, not 
real wav files. For converting you can use sox, for example:</para>
<example id="converting-with-sox">
<title>Converting raw files to real Wave files with sox</title>
<para>
To convert a raw file recorded with &krec; use the following command line inside 
a console (&konsole;), assuming <command>sox</command> is installed. In the example, the file 
is called test.raw and wants to be converted to test.wav. Use your own filenames 
for that.
</para>
<para><screen>
<prompt>&percnt;</prompt><command>sox -r 44100 -c 2 -s -w test.raw 
test.wav</command>
</screen></para>
<para>
The options <option>-r 44100 -c 2 -s -w</option> tell <command>sox</command> 
that you recorded with 44100kHz sampling rate, two channels (stereo), encoded 
signed linear and 16bit words. You may have to use other options for your 
setup - look at the man page of <command>sox</command>.
</para>
</example>
</answer>
</qandaentry>

</qandaset>
</chapter>


<chapter id="credits">
<title>Credits and License</title>

<para>
&krec;
</para>
<para>
Program copyright 2002 Arnold Krille<email>arnold@arnoldarts.de</email>
</para>


<para>
Documentation copyright 2002 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;, you need &kde; 3.1. 
</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:
-->
