path: root/doc/krec/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&krec;">
  <!ENTITY package "tdemultimedia">
  <!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>[email protected]</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>tdemultimedia</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 tdemultimedia 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 &amp; 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 &amp; 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>[email protected]</email>
</para>
<para>
Documentation copyright 2002-2004 Arnold Krille <email>[email protected]</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 tdemultimedia 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:
-->