path: root/doc/tdeioslave/audiocd/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<article lang="&language;" id="audiocd">
<title>audiocd</title>

<articleinfo>

<authorgroup>
<author>&Rik.Hemsley;</author>
<author><personname><firstname>Benjamin</firstname><surname>Meyer</surname></personname></author>
<author>&tde-authors;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<releaseinfo>&tde-release-version;</releaseinfo>
<date>Reviewed: &tde-release-date;</date>

<copyright>
<year>2004</year>
<holder>&Rik.Hemsley;</holder>
<holder>Benjamin Meyer</holder>
</copyright>
<copyright>
<year>&tde-copyright-date;</year>
<holder>&tde-team;</holder>
</copyright>

<abstract>
<para>
This handbook describes the audiocd protocol.
</para>
</abstract>

<keywordset>
<keyword>TDE</keyword>
<keyword>audio</keyword>
<keyword>cd</keyword>
</keywordset>

</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, &eg;
<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, &eg;
<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, &eg;
<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, &eg;
<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&amp;paranoia_level=0&amp;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 tdeio_audiocd which device your &CD-ROM; is.</para> 
</answer>
</qandaentry>
</qandaset>


</article>