summaryrefslogtreecommitdiffstats
path: root/doc/krec/index.docbook
diff options
context:
space:
mode:
Diffstat (limited to 'doc/krec/index.docbook')
-rw-r--r--doc/krec/index.docbook639
1 files changed, 639 insertions, 0 deletions
diff --git a/doc/krec/index.docbook b/doc/krec/index.docbook
new file mode 100644
index 0000000..38665c9
--- /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 &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>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:
+-->