Warning, /multimedia/audiocd-kio/doc/index.docbook is written in an unsupported language. File is not indexed.

0001 <?xml version="1.0" ?>
0002 <!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
0003 "dtd/kdedbx45.dtd" [
0004 <!ENTITY % addindex "IGNORE">
0005 <!ENTITY % English "INCLUDE" > <!-- change language only here -->
0006 ]>
0008 <article lang="&language;" id="audiocd">
0009 <title>audiocd</title>
0010 <articleinfo>
0011 <authorgroup>
0012 <author>&Rik.Hemsley; &Rik.Hemsley.mail;</author>
0013 <author><personname><firstname>Benjamin</firstname><surname>Meyer</surname></personname></author>
0015 </authorgroup>
0017 <date>2004-09-16</date>
0018 <releaseinfo>2.30.00</releaseinfo>
0020 </articleinfo>
0022 <para>Allows treating audio <acronym>CD</acronym>s like a
0023 <quote>real</quote> filesystem, where tracks are represented as files
0024 and, when copied from the folder, are digitally extracted from the
0025 <acronym>CD</acronym>. This ensures a perfect copy of the audio
0026 data.</para>
0028 <para>To see how this KIO worker works, insert an audio <acronym>CD</acronym>
0029 in your &CD-ROM; drive and type <userinput>audiocd:/</userinput> into
0030 &konqueror;. Within a few seconds you should see a list of tracks and
0031 some folders.</para>
0033 <para>Audio <acronym>CD</acronym>s don't really have folders, but
0034 the audiocd KIO worker provides them as a convenience. If you look inside
0035 these folders you will see that they all contain the same number of
0036 tracks. If you are connected to the Internet, some folders will have
0037 the actual track titles shown as the filenames.</para>
0039 <para>The reason that these separate folders exist are so that you
0040 can choose in which format you would like to listen to (or copy) the
0041 tracks on the <acronym>CD</acronym>.</para>
0043 <para>If you drag a track from the <filename class="directory">Ogg
0044 Vorbis</filename> folder and drop it on another &konqueror; window
0045 open at your home folder, you should see a progress window showing
0046 you that the track is being extracted from the <acronym>CD</acronym> and
0047 saved to a file. Note that Ogg Vorbis is a compressed format, so the
0048 file in your home folder will appear a great deal smaller than it
0049 would have been if you had copied the raw data.</para>
0051 <para>The mechanism behind this is quite simple. When the audiocd KIO worker
0052 is asked to retrieve a track from the <filename class="directory">Ogg
0053 Vorbis</filename> folder, it starts extracting the digital audio data
0054 from the <acronym>CD</acronym>. As it sends the data over to the file in
0055 your home folder, it simultaneously encodes it in Ogg Vorbis format
0056 (<acronym>CD</acronym> audio is in an uncompressed format to start
0057 with).</para>
0059 <para>You could also try dragging a file ending in <literal
0060 role="extension">.wav</literal> and dropping it on the &kde; Media
0061 Player, &juk;. In this case, the procedure that happens behind the
0062 scenes is similar, except that instead of encoding the audio data in Ogg
0063 Vorbis format, it is put through a very simple conversion, from raw
0064 binary data (which the <literal role="extension">.cda</literal> files in
0065 the toplevel folder represent) to <quote>RIFF WAV</quote> format, a
0066 non-compressed format that most media players understand.</para>
0068 <para>&juk; should quite happily play the <literal
0069 role="extension">.wav</literal> file, but if it has trouble, you may
0070 consider using the <option>paranoia_level</option> option, explained
0071 below.</para>
0073 <variablelist>
0074 <title>Options</title>
0076 <varlistentry>
0077 <term><option>device</option></term>
0078 <listitem>
0079 <para>Set the path to the audio <acronym>CD</acronym> device, &eg;
0080 <userinput>audiocd:/<option>?device</option>=<parameter>/dev/sdc</parameter></userinput>.
0081 Normally, the KIO worker will try to find a <acronym>CD</acronym> drive with
0082 an audio <acronym>CD</acronym> inserted, but if it fails or you have
0083 more than one <acronym>CD</acronym> drive, you may want to try this
0084 option. Note that the configuration dialog allows you to set a default
0085 value for this option.</para>
0086 </listitem>
0087 </varlistentry>
0089 <varlistentry>
0090 <term><option>fileNameTemplate</option></term>
0091 <listitem>
0092 <para>Set the file name template, &eg;
0093 <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>
0094 </listitem>
0095 </varlistentry>
0097 <varlistentry>
0098 <term><option>albumNameTemplate</option></term>
0099 <listitem>
0100 <para>Set the album name template, &eg;
0101 <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>
0102 </listitem>
0103 </varlistentry>
0105 <varlistentry>
0106 <term><option>niceLevel</option></term>
0107 <listitem>
0108 <para>Sets the process nice level for encoders, &eg;
0109 <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>
0110 </listitem>
0111 </varlistentry>
0113 <varlistentry>
0114 <term><option>paranoia_level</option></term>
0115 <listitem>
0116 <para>Set the amount of error detection and correction used when
0117 extracting data.</para>
0119 <variablelist>
0120 <varlistentry>
0121 <term>Level 0</term>
0122 <listitem>
0123 <para>No detection or correction. Only useful if you have a perfect
0124 <acronym>CD</acronym> drive (unlikely).</para>
0125 </listitem>
0126 </varlistentry>
0128 <varlistentry>
0129 <term>Level 1</term>
0130 <listitem>
0131 <para>Enable basic error checking and correction.</para>
0132 </listitem>
0133 </varlistentry>
0135 <varlistentry>
0136 <term>Level 2</term>
0137 <listitem>
0138 <para>Default.  Specifies that only a perfect extraction will be
0139 accepted.</para>
0140 </listitem>
0141 </varlistentry>
0142 </variablelist>
0144 <para>Note that there is a disadvantage to level 2. Extraction can be
0145 very slow, so real-time digital playback may not work properly. If you
0146 have a good quality <acronym>CD</acronym> drive (note that more
0147 expensive does not necessarily mean better quality) then you probably
0148 won't experience very slow extraction, but a poor drive may take days
0149 (!) to extract the audio from one <acronym>CD</acronym>.</para>
0150 </listitem>
0151 </varlistentry>
0153 <varlistentry>
0154 <term><option>cddbChoice</option></term>
0155 <listitem>
0157 <para>Specify which Internet <acronym>CD</acronym> Database entry to use.  Audio
0158 <acronym>CD</acronym>s don't have track names, but the Internet
0159 <acronym>CD</acronym> Database is a clever system which uses a special
0160 unique identifier generated from the number and length of tracks on each
0161 <acronym>CD</acronym> to cross-reference a track listing. Track listings
0162 are contributed by the Internet community and made available to
0163 all.  Occasionally there will be multiple entries.  You can specify which one to use.</para>
0165 <para>You can submit your own track listings using &kscd;, the &kde;
0166 <acronym>CD</acronym> player.</para>
0168 <para>By default audiocd tries to pick the best one.</para>
0169 </listitem>
0170 </varlistentry>
0171 </variablelist>
0173 <variablelist>
0174 <title>Examples</title>
0175 <varlistentry>
0176 <term><userinput>audiocd:/?device=/dev/scd0&amp;paranoia_level=0&amp;cddbChoice=0</userinput></term>
0177 <listitem>
0178 <para>Gives a listing of the tracks on the audio <acronym>CD</acronym>
0179 inserted in <filename class="devicefile">/dev/scd0</filename>, which on
0180 &Linux; specifies the first <acronym>SCSI</acronym> &CD-ROM; device. If
0181 you copy tracks from the <acronym>CD</acronym>, digital extraction will
0182 be performed without error correction or detection. The 
0183 <acronym>CDDB</acronym> Database entry 0 will be used.</para>
0184 </listitem>
0185 </varlistentry>
0186 </variablelist>
0188 <qandaset>
0189 <title>Frequently Asked Question</title>
0190 <qandaentry>
0191 <question>
0192 <para>I get <errorname>The file or folder / does not
0193 exist</errorname>.  How do I fix that? I have an audio
0194 <acronym>CD</acronym> in my drive!</para>
0195 </question>
0197 <answer>
0198 <para>Try running <userinput><command>cdparanoia</command>
0199 <option>-vsQ</option></userinput> as yourself (not <systemitem
0200 class="username">root</systemitem>). Do you see a track list? If not,
0201 make sure you have permission to access the <acronym>CD</acronym>
0202 device. If you're using <acronym>SCSI</acronym> emulation (possible if
0203 you have an <acronym>IDE</acronym> <acronym>CD</acronym> writer) then
0204 make sure you check that you have read and write permissions on the 
0205 generic <acronym>SCSI</acronym> device, which is probably <filename
0206 class="devicefile">/dev/sg0</filename>, <filename
0207 class="devicefile">/dev/sg1</filename>, &etc; If it still doesn't work,
0208 try typing <userinput>audiocd:/?device=/dev/sg0</userinput> (or similar)
0209 to tell kio_audiocd which device your &CD-ROM; is.</para> 
0210 </answer>
0211 </qandaentry>
0212 </qandaset>
0215 </article>