[audiocd-kio] kcmaudiocd: Add Audiocd KCM docs
Yuri Chornoivan
null at kde.org
Fri Feb 8 17:50:20 GMT 2019
Git commit 6f03cc3c702c01ee4a6af13de1250f2df84f5358 by Yuri Chornoivan.
Committed on 08/02/2019 at 17:50.
Pushed by yurchor into branch 'master'.
Add Audiocd KCM docs
M +3 -0 kcmaudiocd/CMakeLists.txt
M +1 -0 kcmaudiocd/audiocd.desktop
A +3 -0 kcmaudiocd/doc/CMakeLists.txt
A +- -- kcmaudiocd/doc/flac.png
A +- -- kcmaudiocd/doc/general.png
A +280 -0 kcmaudiocd/doc/index.docbook
A +- -- kcmaudiocd/doc/mp3.png
A +- -- kcmaudiocd/doc/names.png
A +- -- kcmaudiocd/doc/ogg.png
A +- -- kcmaudiocd/doc/opus.png
M +1 -1 kcmaudiocd/kcmaudiocd.cpp
https://commits.kde.org/audiocd-kio/6f03cc3c702c01ee4a6af13de1250f2df84f5358
diff --git a/kcmaudiocd/CMakeLists.txt b/kcmaudiocd/CMakeLists.txt
index 9760043..9fdace5 100644
--- a/kcmaudiocd/CMakeLists.txt
+++ b/kcmaudiocd/CMakeLists.txt
@@ -25,3 +25,6 @@ install(TARGETS kcm_audiocd DESTINATION ${PLUGIN_INSTALL_DIR})
install(FILES audiocd.desktop DESTINATION ${SERVICES_INSTALL_DIR})
+########### add handbook ################
+
+add_subdirectory(doc)
diff --git a/kcmaudiocd/audiocd.desktop b/kcmaudiocd/audiocd.desktop
index 7e10e99..9a820d7 100644
--- a/kcmaudiocd/audiocd.desktop
+++ b/kcmaudiocd/audiocd.desktop
@@ -3,6 +3,7 @@ Exec=kcmshell5 audiocd
Icon=media-optical-audio
Type=Service
ServiceTypes=KCModule
+X-DocPath=kcontrol/audiocd/index.html
X-KDE-Library=kcm_audiocd
X-KDE-ParentApp=kcontrol
diff --git a/kcmaudiocd/doc/CMakeLists.txt b/kcmaudiocd/doc/CMakeLists.txt
new file mode 100644
index 0000000..810f240
--- /dev/null
+++ b/kcmaudiocd/doc/CMakeLists.txt
@@ -0,0 +1,3 @@
+########### install files ###############
+#
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en SUBDIR kcontrol/audiocd)
diff --git a/kcmaudiocd/doc/flac.png b/kcmaudiocd/doc/flac.png
new file mode 100644
index 0000000..19792c7
Binary files /dev/null and b/kcmaudiocd/doc/flac.png differ
diff --git a/kcmaudiocd/doc/general.png b/kcmaudiocd/doc/general.png
new file mode 100644
index 0000000..f849ee5
Binary files /dev/null and b/kcmaudiocd/doc/general.png differ
diff --git a/kcmaudiocd/doc/index.docbook b/kcmaudiocd/doc/index.docbook
new file mode 100644
index 0000000..8efd4a2
--- /dev/null
+++ b/kcmaudiocd/doc/index.docbook
@@ -0,0 +1,280 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE">
+]>
+<article id="kcm_audiocd" lang="&language;">
+
+<articleinfo>
+<title>Audio-CD</title>
+
+<authorgroup>
+<author><firstname>Yuri</firstname>
+<surname>Chornoivan</surname>
+<affiliation><address>yurchor at ukr.net</address></affiliation></author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</authorgroup>
+
+<date>2019-02-08</date>
+<releaseinfo>Applications 19.04</releaseinfo>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>System Settings</keyword>
+<keyword>audio</keyword>
+<keyword>compact disc</keyword>
+<keyword>cdda</keyword>
+<keyword>wav</keyword>
+<keyword>mp3</keyword>
+<keyword>ogg</keyword>
+<keyword>FLAC</keyword>
+<keyword>opus</keyword>
+</keywordset>
+</articleinfo>
+
+<sect1 id="audiocd-page">
+<title>Audiocd IO Slave Configuration</title>
+<para>The module <guilabel>Audiocd IO Slave Configuration</guilabel> page is divided in the <guilabel>General</guilabel> tab, the <guilabel>Names</guilabel> tab, and the encoder parameter tabs.</para>
+
+<sect2 id="general-tab">
+<title>The General Tab</title>
+<screenshot>
+<screeninfo>The <guilabel>General</guilabel> tab</screeninfo>
+<mediaobject>
+<imageobject> <imagedata fileref="general.png" format="PNG"/> </imageobject>
+<textobject><phrase>The <guilabel>General</guilabel> tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<para>This tab contains the general parameters which apply to the whole process of reading data from CD.</para>
+
+<variablelist>
+<varlistentry><term><guilabel>Use error correction when reading the CD</guilabel></term>
+<listitem>
+<para>When writing Audio CD, the process adds 64 bits of error correction data to each frame. After this, 8 bits of subcode or subchannel data are added to each of the encoded frames, which is used for control and addressing when playing the CD. Ignoring such data correction can speed up reading but can also produce some unwanted artifacts.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term><guilabel>Skip on errors</guilabel></term>
+<listitem>
+<para>The default is never skipping on errors of the medium. This is needed to ensure the high quality of the results.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term><guilabel>Encoder Priority</guilabel></term>
+<listitem>
+<para>It is possible to determine encoder priority to ensure that the encoder process will not prevent you from doing some other tasks in parallel (the lower values) or to speed up the encoding (the higher values).
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="names-tab">
+<title>The Names Tab</title>
+
+<screenshot>
+<screeninfo>The <guilabel>Names</guilabel> tab</screeninfo>
+<mediaobject>
+<imageobject> <imagedata fileref="names.png" format="PNG"/> </imageobject>
+<textobject><phrase>The <guilabel>Names</guilabel> tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<para>The <guilabel>Names</guilabel> tab can be used to fine-tune the file names for the encoded data. It is possible to use some macros and <ulink url="https://en.wikipedia.org/wiki/Regular_expression">regular expressions</ulink> to produce the names exactly to your needs.</para>
+
+<para>You can use the interactive testing field at the bottom part of the page to prove that the correct names will be produced.</para>
+
+</sect2>
+
+<sect2 id="flac-tab">
+<title>The FLAC Encoder Tab</title>
+
+<screenshot>
+<screeninfo>The <guilabel>FLAC Encoder</guilabel> tab</screeninfo>
+<mediaobject>
+<imageobject> <imagedata fileref="flac.png" format="PNG"/> </imageobject>
+<textobject><phrase>The <guilabel>FLAC Encoder</guilabel> tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<note>
+<para>The FLAC encoder tab is only available if Audiocd IO slave was compiled with libFLAC.</para>
+</note>
+
+<para>FLAC is a lossless compressed audio format free of any patents or license fees. It maintains perfect CD audio quality while reducing file size by
+about 50%. When using this codec the filesize is much larger than Opus, Ogg Vorbis or MP3.</para>
+
+<variablelist>
+<varlistentry><term><guilabel>Flac compression level</guilabel></term>
+<listitem>
+<para>The compression level is an integer value between 0 and 8 that represents the tradeoff between file size and compression speed.</para>
+<para> Setting the compression level to 0 yields the shortest compression time but generates a comparably big file.</para>
+<para>On the other hand, a compression level of 8 makes compression quite slow but produces the smallest file.</para>
+<para>Note that since FLAC is by definition a lossless codec, the audio quality of the output is exactly the same regardless of the compression level.</para>
+<para>Also, levels above 5 dramatically increase compression time but create an only slightly smaller file, and are not recommended.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="mp3-tab">
+<title>The MP3 Encoder Tab</title>
+
+<screenshot>
+<screeninfo>The <guilabel>MP3 Encoder</guilabel> tab</screeninfo>
+<mediaobject>
+<imageobject> <imagedata fileref="mp3.png" format="PNG"/> </imageobject>
+<textobject><phrase>The <guilabel>MP3 Encoder</guilabel> tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<note>
+<para>The MP3 encoder tab is only available if <ulink url="http://lame.sourceforge.net/">LAME</ulink> utilities are installed in the system.</para>
+</note>
+
+<para>MP3 (or MPEG-1 Audio Layer III) is a patented digital audio codec using a form of lossy data compression. In spite of its shortcomings, it is a common format for consumer audio storage, and is widely supported on portable music players.</para>
+
+<para>Audiocd IO slave uses the LAME encoder to produce <filename class="extension">mp3</filename> files. LAME is considered the best MP3 encoder, mostly thanks to the dedicated work of its developers and the open source licensing model that allowed the project to tap into engineering resources from all around the world.</para>
+
+<variablelist>
+<varlistentry><term><guilabel>Encoding Method</guilabel></term>
+<listitem>
+<para>The bitrate is a measure of the quantity of data used to represent a second of the audio track. It is possible to determine <guilabel>Constant bitrate</guilabel> for predictable file size. The MP3 encoder also supports a <guilabel>Variable bitrate</guilabel> setting, which means that the bitrate value fluctuates along the track based on the complexity of the audio content. More complex intervals of data are encoded with a higher bitrate than less complex ones; this approach yields overall better quality and a smaller file than having a constant bitrate throughout the track.</para>
+<para>You can also define the quality of encoding. The lower quality can speed up the encoding process for the price of some data loss.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term><guilabel>Options</guilabel></term>
+<listitem>
+<para>Check the <guilabel>Copyrighted</guilabel> item if the produced data are copyright protected.</para>
+<para>Check the <guilabel>Original</guilabel> item if the extraction of data is made from the original &CD;.</para>
+<para>When the <guilabel>ISO encoding</guilabel> item is chacked, LAME will enforce the 7680 bit limitation on total frame size. The compatibility with ISO might be important for hardware players.</para>
+<para>The CRC <guilabel>Error Protection</guilabel> item can be used to add a checksum to each data frame. Such protection can enhance the stability of the MP3 data storing.</para>
+<para>The <guilabel>Write ID3 tag</guilabel> item is used to enforce LAME to write <ulink url="https://en.wikipedia.org/wiki/ID3">ID3 metadata</ulink> to each produced MP3 file.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term><guilabel>Filter Settings</guilabel></term>
+<listitem>
+<para>It is possible to apply bandwidth filtering to the data. It is used to limit the high or low frequencies that are encoded. Most of us cannot hear the high frequencies anyway, and they are the most <quote>expensive</quote> bitwise, when it comes to encoding. They also tend to be the cause of artifacts.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term><guilabel>Variable Bitrate Settings</guilabel></term>
+<listitem>
+
+<para>You can also choose <guilabel>Average bitrate</guilabel>, which is the default, or <guilabel>Maximal bitrate</guilabel>, <guilabel>Minimal bitrate</guilabel> and whether <guilabel>Minimal value is a hard limit</guilabel>.</para>
+<para>160 kb/s is a good choice for music listening on a portable player. Anything below 120 kb/s might be unsatisfactory for music and anything above 256 kb/s is probably overkill.</para>
+<para>It is also possible to <guilabel>Write Xing VBR tag</guilabel> into the file. Xing was responsible for creating an encoder notable for its VBR tag, which enables more accurate seeking within variable bitrate files. Among other things, Xing's VBR tag contains information about the total duration of an MP3 file, something that is not otherwise readily available from the MPEG stream.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="opus-tab">
+<title>The Opus Encoder Tab</title>
+
+<screenshot>
+<screeninfo>The <guilabel>Opus Encoder</guilabel> tab</screeninfo>
+<mediaobject>
+<imageobject> <imagedata fileref="opus.png" format="PNG"/> </imageobject>
+<textobject><phrase>The <guilabel>Opus Encoder</guilabel> tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<note>
+<para>The Opus encoder tab is only available if <ulink url="http://opus-codec.org/">opus-tools</ulink> are installed in the system.</para>
+</note>
+
+<para>Opus is a totally open, royalty-free, highly versatile audio codec. Opus is unmatched for interactive speech and music transmission over the Internet, but is also intended for storage and streaming applications.</para>
+
+<variablelist>
+<varlistentry><term><guilabel>Encoding Method</guilabel></term>
+<listitem>
+<para>This setting allows you to choose between <guilabel>Complexity based</guilabel> and <guilabel>Bitrate based</guilabel> encoding. The complexity based encoding uses some speculative algorithms for the price of an unpredictable size of the results.</para>
+<itemizedlist>
+<listitem>
+<para>There are several things which influence the Opus encoder choice between CPU complexity and quality/bitrate. The complexity of encoding can be selected using an integer from 0 to 10, where 0 yields the lowest quality and 10 yields the highest quality.</para>
+</listitem>
+<listitem>
+<para>Opus is more efficient when operating with variable bitrate (<guilabel>Average variable bitrate</guilabel>), which is the default. It is possible to use constrained variable bitrate (<guilabel>Constrained variable bitrate</guilabel>, an analog of constant bitrate for MP3) when the low-latency transmission is required over a relatively slow connection. In some (rare) applications, constant bitrate (<guilabel>Constant bitrate</guilabel>) is required.</para>
+<para>It is recommended to use 64-128 kbit/s bitrate for stereo music.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+<varlistentry><term><guilabel>Add track information</guilabel></term>
+<listitem>
+<para>When checked, add a description of the song to the file header. This makes it easy for the user to get advanced song information shown by his media player. You can get
+this information automatically via the Internet. Look at the &systemsettings; CDDB Retrieval module for details.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="ogg-tab">
+<title>The Ogg Vorbis Encoder Tab</title>
+
+<screenshot>
+<screeninfo>The <guilabel>Ogg Vorbis Encoder</guilabel> tab</screeninfo>
+<mediaobject>
+<imageobject> <imagedata fileref="ogg.png" format="PNG"/> </imageobject>
+<textobject><phrase>The <guilabel>Ogg Vorbis Encoder</guilabel> tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<note>
+<para>The Ogg Vorbis encoder tab is only available if Audiocd IO slave was compiled with <ulink url="https://xiph.org/vorbis/">libvorbis</ulink>.</para>
+</note>
+
+<para>Ogg Vorbis is an open and royalty-free audio codec for lossy audio compression. It produces smaller files than MP3 at equivalent or higher quality.</para>
+
+<variablelist>
+<varlistentry><term><guilabel>Encoding Method</guilabel></term>
+<listitem>
+<para>This setting allows you to choose between <guilabel>Quality based</guilabel> and <guilabel>Bitrate based</guilabel> encoding. The quality based encoding uses some speculative algorithms at a price of the unpredictable size of the results.</para>
+<itemizedlist>
+<listitem>
+<para>The quality of Ogg Vorbis encoding can be selected using an integer from 0 to 10, where 0 yields the lowest quality and 10 yields the highest quality.</para>
+</listitem>
+<listitem>
+<para>As an alternative variable bitrate can be used. It is possible to choose <guilabel>Average bitrate</guilabel>, which is the default, or <guilabel>Maximal bitrate</guilabel> and <guilabel>Minimal bitrate</guilabel>.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+<varlistentry><term><guilabel>Add track information</guilabel></term>
+<listitem>
+<para>When checked, add a description of the song to the file header. This makes it easy for the user to get advanced song information shown by his media player. You can get
+this information automatically via the Internet. Look at the &systemsettings; CDDB Retrieval module for details.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+</sect1>
+</article>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab
+kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
+-->
diff --git a/kcmaudiocd/doc/mp3.png b/kcmaudiocd/doc/mp3.png
new file mode 100644
index 0000000..74d41eb
Binary files /dev/null and b/kcmaudiocd/doc/mp3.png differ
diff --git a/kcmaudiocd/doc/names.png b/kcmaudiocd/doc/names.png
new file mode 100644
index 0000000..0075b9a
Binary files /dev/null and b/kcmaudiocd/doc/names.png differ
diff --git a/kcmaudiocd/doc/ogg.png b/kcmaudiocd/doc/ogg.png
new file mode 100644
index 0000000..2839bdf
Binary files /dev/null and b/kcmaudiocd/doc/ogg.png differ
diff --git a/kcmaudiocd/doc/opus.png b/kcmaudiocd/doc/opus.png
new file mode 100644
index 0000000..d8f01e5
Binary files /dev/null and b/kcmaudiocd/doc/opus.png differ
diff --git a/kcmaudiocd/kcmaudiocd.cpp b/kcmaudiocd/kcmaudiocd.cpp
index a236674..3faf706 100644
--- a/kcmaudiocd/kcmaudiocd.cpp
+++ b/kcmaudiocd/kcmaudiocd.cpp
@@ -50,7 +50,7 @@ KAudiocdModule::KAudiocdModule(QWidget *parent, const QVariantList &lst)
audioConfig = new AudiocdConfig(this);
box->addWidget(audioConfig);
- setButtons(Default|Apply);
+ setButtons(Default|Apply|Help);
config = new KConfig( QLatin1String( "kcmaudiocdrc" ));
More information about the kde-doc-english
mailing list