<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kid3 '<application>Kid3</application>'>
  <!ENTITY doublehyphen '--'>
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % German "INCLUDE"><!-- change language only here -->
]>
<book lang="&language;">

<bookinfo>
<title>Das Kid3 Handbuch</title>

<authorgroup>
<author>
<firstname>Urs</firstname>
<surname>Fleisch</surname>
<affiliation>
<address><email>ufleisch@users.sourceforge.net</email></address>
</affiliation>
<contrib>Software Entwicklung</contrib>
</author>
</authorgroup>

<copyright>
<year>2015</year>
<holder>Urs Fleisch</holder>
</copyright>
<legalnotice id="fdl-notice">&FDLNotice;</legalnotice>

<date>2015-10-01</date>
<releaseinfo>3.3.0</releaseinfo>

<abstract>
<para>
&kid3; ist eine Anwendung zum effizienten Editieren von ID3v1 und ID3v2 Tags
in MP3 Dateien. Auch die Tags in Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex,
TrueAudio, WavPack, WMA, WAV, AIFF Dateien und Tracker Modulen (MOD, S3M, IT, XM) werden
unterstützt. Es ist einfach, Tags in mehreren Dateien auf die gleichen Werte
zu setzen (z.B. Album, Interpret, Jahr und Genre in allen Dateien eines Albums),
Tags aus den Dateinamen zu generieren oder umgekehrt.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdemultimedia</keyword>
<keyword>MP3</keyword>
<keyword>ID3</keyword>
<keyword>ID3v1</keyword>
<keyword>ID3v2</keyword>
<keyword>Ogg</keyword>
<keyword>Vorbis</keyword>
<keyword>FLAC</keyword>
<keyword>MPC</keyword>
<keyword>APE</keyword>
<keyword>Musepack</keyword>
<keyword>MP4</keyword>
<keyword>M4A</keyword>
<keyword>MP2</keyword>
<keyword>Speex</keyword>
<keyword>TrueAudio</keyword>
<keyword>WavPack</keyword>
<keyword>WMA</keyword>
<keyword>WAV</keyword>
<keyword>AIFF</keyword>
<keyword>MOD</keyword>
<keyword>S3M</keyword>
<keyword>IT</keyword>
<keyword>XM</keyword>
<keyword>Opus</keyword>
<keyword>DSF</keyword>
</keywordset>

</bookinfo>

<!--begin manpage include
<refmeta>
<refentrytitle>kid3</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>kid3</refname>
<refname>kid3-qt</refname>
<refname>kid3-cli</refname>
<refpurpose>Kid3 ID3 Tagger</refpurpose>
</refnamediv>
end manpage include-->

<!--change manpage<refsynopsisdiv>--><preface id="synopsis"><title>Übersicht</title>
<cmdsynopsis>
<command>kid3</command>
<group>
<arg choice="plain"><option>&doublehyphen;help</option></arg>
<arg choice="plain"><option>&doublehyphen;help-qt</option></arg>
<arg choice="plain"><option>&doublehyphen;help-kde</option></arg>
<arg choice="plain"><option>&doublehyphen;help-all</option></arg>
<sbr/>
<arg choice="plain"><option>&doublehyphen;author</option></arg>
<arg choice="plain"><option>&doublehyphen;version</option></arg>
<arg choice="plain"><option>&doublehyphen;license</option></arg>
</group>
<arg rep="repeat"><replaceable>DATEI</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>kid3-qt</command>
<arg><option>Qt-Optionen</option></arg>
<arg rep="repeat"><replaceable>DATEI</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>kid3-cli</command>
<group>
<arg choice="plain"><option>-h</option></arg>
<arg choice="plain"><option>&doublehyphen;help</option></arg>
</group>
<arg><option>-c BEFEHL1</option></arg>
<arg rep="repeat"><option>-c BEFEHL2</option></arg>
<arg rep="repeat"><replaceable>DATEI</replaceable></arg>
</cmdsynopsis>
<!--change manpage</refsynopsisdiv>--></preface>

<preface id="options"><title>Optionen</title>

<variablelist>
<varlistentry>
<term><replaceable>DATEI</replaceable></term>
<listitem><para>Wenn <filename><replaceable>DATEI</replaceable></filename> der
Pfad auf ein Verzeichnis ist, so wird es geöffnet. Wenn einer oder mehrere
Datei-Pfade gegeben werden, so wird deren gemeinsames Verzeichnis geöffnet und
die Dateien werden ausgewählt.
 </para></listitem>
</varlistentry>
</variablelist>

<sect1 id="options-kid3"><title>kid3</title>
<variablelist>
<varlistentry>
<term><option>&doublehyphen;help</option></term>
<listitem><para>Hilfe zu verfügbaren Optionen anzeigen.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>&doublehyphen;help-qt</option></term>
<listitem><para>Spezielle Optionen zu Qt anzeigen, siehe
<citerefentry><refentrytitle>qtoptions</refentrytitle><manvolnum>7</manvolnum>
</citerefentry>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>&doublehyphen;help-kde</option></term>
<listitem><para>Spezielle Optionen zu KDE anzeigen, siehe
<citerefentry><refentrytitle>kdeoptions</refentrytitle><manvolnum>7</manvolnum>
</citerefentry>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>&doublehyphen;help-all</option></term>
<listitem><para>Alle Optionen anzeigen.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>&doublehyphen;author</option></term>
<listitem><para>Autoren-Information anzeigen.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>&doublehyphen;version</option></term>
<listitem><para>Versionsinformation anzeigen.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>&doublehyphen;license</option></term>
<listitem><para>Lizenz-Informationen anzeigen.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="options-kid3-qt"><title>kid3-qt</title>
<variablelist>
<varlistentry>
<term><option>Qt-Optionen</option></term>
<listitem><para>Siehe <citerefentry><refentrytitle>qtoptions</refentrytitle>
<manvolnum>7</manvolnum></citerefentry>, die Optionen haben jedoch einen "-"
als Präfix, und nicht "&doublehyphen;".</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="options-kid3-cli"><title>kid3-cli</title>
<variablelist>

<varlistentry>
<term><option>-c</option></term>
<listitem><para>Führe einen Befehl aus. Mehrere <option>-c</option> Optionen sind möglich, die Befehle werden in der entsprechenden Reihenfolge ausgeführt.
Siehe den Abschnitt über <link linkend="kid3-cli">kid3-cli</link> für eine
Beschreibung der verfügbaren Befehle.</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-h</option>|<option>&doublehyphen;help</option></term>
<listitem><para>Hilfe zu verfügbaren Optionen und Befehlen anzeigen.
</para></listitem>
</varlistentry>

</variablelist>
</sect1>

</preface>

<chapter id="introduction">
<title>Einleitung</title>

<para>
&kid3; ist eine Anwendung zum effizienten Editieren von ID3v1 und ID3v2 Tags
in MP3 Dateien. Diese Tags können zwar mit den meisten MP3 Player
Programmen editiert werden, jedoch nicht auf eine sehr komfortable und
effiziente Art. Darüber hinaus werden auch die Tags in Ogg/Vorbis, Opus, DSF, FLAC,
MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF Dateien
und Tracker Modulen (MOD, S3M, IT, XM) unterstützt.
</para>
<para>
&kid3; kann weder MP3 grabben noch codieren, es ist darauf
ausgelegt, die ID3 Tags von allen Dateien eines Albums auf eine möglichst
effiziente Art zu editieren, d.h. mit so wenig Mausklicks und Tastendrücken
wie möglich. Während die meisten anderen Programme entweder ID3v1 oder
ID3v2 Tags editieren können, hat &kid3; volle Kontrolle über die Tags
beider Versionen, es kann zwischen den beiden Formaten konvertieren und hat
Zugang zu allen ID3v2 Frames. Tags mehrerer Dateien können gleichzeitig
auf dieselben Werte gesetzt werden, so beispielsweise Interpret, Album,
Jahr und Genre aller Dateien eines Albums. Wenn die Information für die Tags
schon im Dateinamen enthalten ist, können die Tags automatisch aus dem
Dateinamen generiert werden. Es ist auch möglich, den Dateinamen in einem
beliebigen Format aus den Werten in den Tags zu setzen.
</para>
<para>
Das Editieren wird darüber hinaus durch automatische Ersetzung von
Zeichenketten erleichtert, z.B. um ungültige Zeichen aus Dateinamen zu
entfernen. Automatische Groß- und Kleinschreibung macht es einfach,
eine konsistente Namensschreibweise in allen Tags zu verwenden.
</para>
<para>
Die Tag-Information für ganze Alben kann über
<ulink url="http://gnudb.org">gnudb.org</ulink>, <ulink
url="http://tracktype.org">TrackType.org</ulink>, <ulink
url="http://musicbrainz.org">MusicBrainz</ulink>, <ulink
url="http://discogs.com">Discogs</ulink>, <ulink
url="http://www.amazon.com">Amazon</ulink> oder von anderen Quellen mit
Albuminformationen importiert werden. Das verwendete Format ist mit regulären
Ausdrücken frei konfigurierbar.
</para>
<para>
Probleme und Vorschläge für neue Funktionen können dem Autor gemeldet
werden.
</para>
</chapter>

<chapter id="using-kid3">
<title>Benutzen von Kid3</title>

<sect1 id="kid3-features">
<title>Funktionsmerkmale von Kid3</title>
<itemizedlist>
<listitem><para>Editieren von ID3v1.1 Tags</para></listitem>
<listitem><para>Editieren von allen ID3v2.3 und ID3v2.4 Frames</para></listitem>
<listitem><para>Editieren der Tags von mehreren Dateien</para></listitem>
<listitem><para>Konvertieren zwischen ID3v1 und ID3v2 Tags</para></listitem>
<listitem><para>Editieren von MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex,
TrueAudio, WavPack, WMA, WAV und AIFF Tags</para></listitem>
<listitem><para>Generieren der Tags aus dem Dateinamen</para></listitem>
<listitem><para>Generieren der Tags aus dem Inhalt der Tagfelder</para></listitem>
<listitem><para>Generieren des Dateinamens aus den Tags</para></listitem>
<listitem><para>Generieren und Ändern des Verzeichnisnamens aus den Tags</para></listitem>
<listitem><para>Generieren von Stücklisten</para></listitem>
<listitem><para>Automatische Groß-/Kleinschreibung und Zeichenersetzung</para></listitem>
<listitem><para>Import von <ulink url="http://gnudb.org">gnudb.org</ulink>,
<ulink url="http://tracktype.org">TrackType.org</ulink>,
<ulink url="http://musicbrainz.org">MusicBrainz</ulink>,
<ulink url="http://discogs.com">Discogs</ulink>,
<ulink url="http://www.amazon.com">Amazon</ulink>
und anderen Quellen</para></listitem>
<listitem><para>Export als CSV, HTML, Stückliste, Kover XML oder in
anderen Formaten. Exportierte CSV-Dateien können wieder importiert
werden.</para></listitem>
</itemizedlist>
</sect1>

<sect1 id="example-usage">
<title>Arbeiten anhand eines Beispiels</title>
<para>
Dieser Abschnitt beschreibt eine typische Sitzung mit &kid3;. Nehmen wir an,
wir haben ein Verzeichnis mit MP3 Dateien der Stücke aus dem Album "Let's Tag"
von der Gruppe "One Hit Wonder". Das Verzeichnis ist im "Interpret - Album"
Format benannt, in unserem Fall also <filename>One Hit Wonder - Let's
Tag</filename>. Das Verzeichnis enthält die Stücke im "Nummer Titel.mp3"
Format, was auch Sinn macht, weil die Dateinamen kurz werden (wichtig bei
den kleinen Anzeigen mobiler MP3 Player) und alphabetisch in der richtigen
Reihenfolge geordnet werden (wichtig falls ein Hardware MP3 Player die
Stücke in alphabetischer Reihenfolge abspielt oder in der Reihenfolge, wie
sie auf CD gebrannt wurde - diese Reihenfolge ist bei <command>mkisofs</command>
alphabetisch). Darüber hinaus sind Interpret und Album bereits im
Verzeichnisnamen enthalten und brauchen nicht im Dateinamen wiederholt zu
werden. Doch zurück zu unserem Beispiel - das Verzeichnis sieht
folgendermaßen aus:
</para>
<para><filename>01 Intro.mp3</filename></para>
<para><filename>02 We Only Got This One.mp3</filename></para>
<para><filename>03 Outro.mp3</filename></para>
<para>
Diese Dateien haben noch keine Tags, wir werden diese mit &kid3; erzeugen.
Wir benutzen <guimenuitem>Öffnen</guimenuitem> (<guimenu>Datei</guimenu> Menü
oder Werkzeugleiste) und wählen eine der Dateien in diesem Verzeichnis. Alle
Dateien werden im Dateilistenfeld angezeigt. Aus Bequemlichkeit wollen
wir die Tags aus den Dateinamen erzeugen. Daher wählen wir alle Dateien im
Listenfeld aus und klicken auf <guilabel>Nach:</guilabel> <guibutton>Tag 1</guibutton> in der
<guilabel>Datei</guilabel> Sektion. Dadurch werden Titel, Interpret,
Album und Nummer in allen Dateien gesetzt. Um die Werte für Jahr und Genre
in allen Dateien zu setzen, lassen wir alle Dateien selektiert und tippen
"2002" in das Feld <guilabel>Jahr</guilabel> und wählen "Pop" im
<guilabel>Genre</guilabel> Auswahlfeld. Um einzig diese zwei Werte zu
verändern, werden ihre Markierungsfelder automatisch aktiviert, und alle anderen Markierungsfelder
bleiben leer. Wird nun durch Klick auf die erste Datei die Auswahl
verändert, so sieht man, dass die Tags für die erste Datei die korrekten
Werte enthalten. Die Tags der anderen Dateien können auch überprüft werden,
indem eine nach der andern selektiert wird. Wenn wir mit den Tags
zufrieden sind, können die Änderungen mit <guimenuitem>Speichern</guimenuitem>
(<guimenu>Datei</guimenu> Menü oder Werkzeugleiste) übernommen werden. Wählen von
<guimenuitem>Stückliste erstellen</guimenuitem> im <guimenu>Datei</guimenu>
Menü erzeugt die Datei <filename>One Hit Wonder - Let's Tag.m3u</filename>
im Verzeichnis.
</para>
</sect1>

</chapter>

<chapter id="commands">
<title>Menüeinträge</title>

<sect1 id="gui-elements">
<title>Die Elemente der Benutzeroberfläche</title>
<para>
Die &kid3; Benutzeroberfläche ist in fünf Sektionen aufgeteilt: Links finden sich das
Dateilistenfeld und das Verzeichnislistenfeld, die rechte Seite enthält
die <guilabel>Datei</guilabel>,
<guilabel>Tag 1</guilabel> und <guilabel>Tag 2</guilabel>
Sektionen.
</para>

<sect2 id="file-list">
<title>Dateiliste</title>

<para>
Die Dateiliste enthält die Namen aller Dateien im geöffneten Verzeichnis,
welche den gewählten Dateinamenfilter (typischerweise <filename>*.mp3
*.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2 *.spx
*.tta *.wv *.wma *.wav *.aiff *.ape</filename>)
erfüllen. Eine einzelne oder mehrere Dateien können ausgewählt werden. Um
keine Datei auszuwählen, kann in den leeren Bereich unterhalb der
Dateieinträge geklickt werden. Die Auswahl bestimmt die Dateien, welche
durch die unten beschriebenen Operationen verändert werden.
</para>
<para>
Nebst <guilabel>Name</guilabel> können noch andere Spalten
<guilabel>Größe</guilabel>, <guilabel>Typ</guilabel> und
<guilabel>Änderungsdatum</guilabel> mit Details zu den Dateien dargestellt
werden. Eine Spalte wird angezeigt, wenn das Häkchen bei ihrem Namen im
Kontextmenü der Kopfzeile gesetzt ist. Die Reihenfolge der Spalten kann
mittels Drag'n'Drop verändert werden. Die Sortierreihenfolge kann durch
Klicken auf den Spaltenkopf umgeschaltet werden.
</para>
<para>
Links von den Namen kann ein Symbol dargestellt werden: eine Diskette, um
zu zeigen, dass die Datei verändert wurde, oder Information über die Tags
welche vorhanden sind (V1, V2, V1V2 oder NO TAG, wenn nichts dargestellt wird,
wurde die Datei noch nicht eingelesen).
</para>
<para>
Verzeichnisse werden mit Ordner-Symbolen gekennzeichnet. Wenn ein Verzeichnis
geöffnet wird, so werden seine Dateien in einem hierarchischen Baum
dargestellt. Operationen können auf Dateien aus verschiedenen
Verzeichnissen angewendet werden, was nützlich ist, wenn die
Musik-Dateien so organisiert werden, dass pro Interpret ein Ordner erstellt
wird, der wiederum ein Verzeichnis für jedes Album enthält.
</para>
<para>
Bei einem Rechtsklick in der Dateiliste öffnet sich ein Kontext-Menü mit
folgenden Befehlen:
<itemizedlist>
<listitem><para>
<guimenuitem>Alle ausklappen</guimenuitem>: Klappt alle Verzeichnisbäume
auf (nur das aktuelle Verzeichnis, wenn die Umschalttaste gedrückt ist)
</para></listitem>
<listitem><para>
<guimenuitem>Alle einklappen</guimenuitem>: Klappt alle Verzeichnisbäume
ein
</para></listitem>
<listitem><para>
<guimenuitem>Umbenennen</guimenuitem>: Ändert den Namen der Datei
</para></listitem>
<listitem><para>
<guimenuitem>In den Mülleimer werfen</guimenuitem>: Verschiebt die Datei in
den Mülleimer</para></listitem>
<listitem><para>
<guimenuitem>Wiedergabe</guimenuitem>: Spielt die Datei ab,
siehe <link linkend="play">Wiedergabe</link>
</para></listitem>
<listitem><para>Bei den weiteren Menüeinträgen handelt es sich um
Benutzerbefehle, welche in <link linkend="configure-kid3">Kid3 einrichten</link>
bei <guilabel>Benutzerbefehle</guilabel> definiert werden können. Dort kann
auch die Wiedergabe von Dateien per Doppelklick aktiviert werden.
</para></listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="directory-list">
<title>Verzeichnisliste</title>

<para>
Die Verzeichnisliste enthält die Verzeichnisse, welche das geöffnete
Verzeichnis enthält, sowie das aktuelle (<filename>.</filename>) und das
übergeordnete (<filename>..</filename>) Verzeichnis. Sie erlaubt den raschen
Wechsel zwischen Verzeichnissen, ohne den Umweg über die
<guimenuitem>Öffnen...</guimenuitem> Funktion oder "Drag and Drop".
</para>
<para>
Die Anzeige, Reihenfolge und Sortierung der Spalten kann auf dieselbe Weise
eingestellt werden wie bei der <link linkend="file-list">Dateiliste</link>
beschrieben.
</para>
</sect2>

<sect2 id="file">
<title>Datei</title>

<para>
Zeigt Informationen über Codierung (MP3,
Ogg, Opus, DSF, FLAC, MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV, AIFF),
Bit- und Samplerate, Kanäle und die Länge der Datei an.
</para>
<para>
Das <guilabel>Name</guilabel> Editierfeld enthält den Dateiname wenn nur
eine einzelne Datei ausgewählt ist. Wird dieses Feld verändert, so wird
die Datei umbenannt, wenn <guimenuitem>Speichern</guimenuitem> ausgeführt
wird.
</para>
<para>
Das <guilabel>Format</guilabel> Auswahl- und Editierfeld enthält das Format,
welches verwendet wird, wenn der Dateiname aus dem ersten oder zweiten Tag
erzeugt wird. Der Dateiname kann beliebige Zeichen enthalten, es kann
sogar ein Verzeichnisteil abgetrennt durch einen Schrägstrich angegeben
werden, doch dieses Verzeichnis muss bereits existieren, damit das
Umbenennen erfolgreich ist. Die folgenden Codes können verwendet werden, um
Werte aus den Tags im Dateinamen einzusetzen:
</para>

<itemizedlist>
<listitem><para>%s %{title} Titel (Song)</para></listitem>
<listitem><para>%a %{artist} Interpret (Artist)</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Kommentar (Comment)</para></listitem>
<listitem><para>%y %{year} Jahr (Year)</para></listitem>
<listitem><para>%t %{track} Nummer (Track, z.B. 01)</para></listitem>
<listitem><para>%t %{track.n} Nummer mit Feldlänge n (z.B. 001 für %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Nummer (Track, z.B. 1)</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>  %{ignore} Wird ignoriert wenn Tags aus dem Dateinamen erzeugt werden</para></listitem>
</itemizedlist>

<para>
Die Formatcodes sind nicht auf die oben gegebenen Beispiele beschränkt. Alle
Framenamen können benutzt werden, sowohl vereinheitlichte
wie <userinput>%{bpm}</userinput> als auch formatspezifische
wie <userinput>%{popm}</userinput>.
</para>

<para>
Ein zweites <guilabel>Format</guilabel> Auswahlfeld (mit Pfeil runter)
wird verwendet, um die Tags aus dem Dateinamen zu
generieren. Falls der Dateinamen nicht diesem Format entspricht, werden noch
einige andere, gängige Formate ausprobiert.
</para>

<para>
Einige häufig verwendete Dateinamen-Formate sind bereits vordefiniert und
über das Auswahlfeld verfügbar, aber es ist auch möglich, ein eigenes Format
in das Eingabefeld einzutragen.
</para>
<para>
<guilabel>Von:</guilabel> <guibutton>Tag 1</guibutton>,
<guibutton>Tag 2</guibutton>: Setzt den Dateinamen gemäß dem
ausgewählten Format und dem ersten Tag bzw. zweiten Tag.
</para>
<para>
<guilabel>Nach:</guilabel> <guibutton>Tag 1</guibutton>,
<guibutton>Tag 2</guibutton>: Die Tags werden anhand des
Dateinamens gesetzt. Dabei wird zuerst das in <guilabel>Format</guilabel>
ausgewählte Dateinamenformat probiert. Falls der vorhandene Dateinamen nicht
diesem Format entspricht, werden noch folgende Formate versucht:
<itemizedlist>
<listitem><para><filename>Interpret - Album/Nummer Titel</filename></para></listitem>
<listitem><para><filename>Album/Nummer - Interpret - Titel</filename></para></listitem>
<listitem><para><filename>/Interpret - Album - Nummer - Titel</filename></para></listitem>
<listitem><para><filename>Album/Interpret - Nummer - Titel</filename></para></listitem>
<listitem><para><filename>Album/Interpret - Titel</filename></para></listitem>
<listitem><para><filename>Artist/Album/Track Song</filename></para></listitem>
</itemizedlist>
Wenn eine einzelne Datei ausgewählt wurde, werden die Eingabefelder mit den
aus dem Dateinamen extrahierten Werten gefüllt. Bei Mehrfachselektion
werden die Werte direkt gemäß den Dateinamen gesetzt.
</para>
</sect2>

<sect2 id="tag1">
<title>Tag 1</title>

<para>
Die Eingabefelder für <guilabel>Titel</guilabel>,
<guilabel>Interpret</guilabel>,
<guilabel>Album</guilabel>, <guilabel>Kommentar</guilabel>,
<guilabel>Jahr</guilabel>, <guilabel>Nummer</guilabel> und
<guilabel>Genre</guilabel> werden benutzt um die entsprechenden Werte im
ersten Tag der ausgewählten Dateien zu editieren. Die Werte werden
verändert, wenn die Dateiauswahl geändert wird oder vor Operationen wie
<guimenuitem>Speichern</guimenuitem> und
<guimenuitem>Beenden</guimenuitem> und wenn die entsprechenden
Markierungsfelder links aktiviert sind. Dies ist nützlich, um nur bestimmte
Werte zu verändern und die übrigen Werte nicht anzurühren.
</para>
<para>
Wenn eine einzelne Datei ausgewählt ist, werden alle Markierungsfelder
aktiviert und die Eingabefelder enthalten die Werte aus den Tags in der
Datei. Wenn ein Tag nicht vorhanden ist, werden die leeren Werte angezeigt,
d.h. eine leere Zeichenkette für die Felder <guilabel>Titel</guilabel>,
<guilabel>Interpret</guilabel>, <guilabel>Album</guilabel> und
<guilabel>Kommentar</guilabel>, 0 für <guilabel>Jahr</guilabel> und
<guilabel>Nummer</guilabel> und ein leerer Auswahleintrag bei
<guilabel>Genre</guilabel>. Die Werte können editiert werden und werden
für die ausgewählte Datei beim Ändern der Auswahl gesetzt, sofern das
entsprechende Markierungsfeld aktiviert ist. Die Datei wird dann durch
ein Disketten-Symbol als modifiziert gekennzeichnet, doch die eigentliche Datei
bleibt unverändert, bis <guimenuitem>Speichern</guimenuitem> ausgeführt
wird.
</para>
<para>
Wenn mehrere Dateien ausgewählt werden, dann werden nur diejenigen Werte
angezeigt, welche bei allen ausgewählten Dateien identisch sind. In allen
übrigen Editierfeldern werden die leeren Werte (siehe oben) angezeigt. Alle
Markierungsfelder sind inaktiv, um ungewolltes Verändern mehrerer Dateien
zu verhindern. Soll ein Wert für alle selektierten Dateien verändert
werden, so kann er editiert werden, und das entsprechende Markierungsfeld
wird gesetzt. Der Wert wird dann für alle ausgewählten Dateien verändert
wenn die Auswahl geändert wird und kann mit <guimenuitem>Speichern</guimenuitem>
gesichert werden.
</para>
<para>
Die Markierungsfelder bestimmen auch, auf welche Felder die meisten anderen
Befehle angewendet werden. So werden beim Kopieren, Einfügen und Transferieren
zwischen Tags 1 und 2 nur markierte Felder verwendet. Um die Bedienung zu
vereinfachen, wenn mehrere Dateien ausgewählt sind und daher alle
Markierungsfelder inaktiv sind, verhalten sich diese Befehle wenn alle
Markierungsfelder inaktiv sind gleich als wären alle markiert.
</para>
<para>
<guibutton>Von Tag 2</guibutton>: Die Tag 1 Felder werden auf die gleichen
Werte gesetzt wie die entsprechenden Tag 2 Werte. Bei Mehrfachselektion
werden die Tags der Dateien direkt gesetzt.
</para>
<para>
<guibutton>Kopieren</guibutton>: Die Kopierablage wird mit den Tag 1 Werten
gefüllt. Bei folgenden Einfüge-Operationen werden nur solche Werte gesetzt,
bei welchen hier das Markierungsfeld aktiviert war.
</para>
<para>
<guibutton>Einfügen</guibutton>: Fügt die Werte aus der Kopierablage in die
Eingabefelder ein.
</para>
<para>
<guibutton>Löschen</guibutton>: Diese Funktion setzt alle Editierfelder auf
die leeren Werte, entfernt also alle Werte. Die gespeicherte Datei enthält
dann kein Tag 1 mehr.
</para>
</sect2>

<sect2 id="tag2">
<title>Tag 2</title>

<para>
Die Eingabefelder funktionieren gleich wie bei <guilabel>Tag 1</guilabel>
beschrieben, die Länge der Zeichenketten ist jedoch nicht begrenzt.
</para>
<para>
Beim <guilabel>Genre</guilabel> können nebst den vorgegebenen auch eigene Namen
verwendet werden - eine Eingabe ins Editierfeld genügt.
</para>
<para>
Das Tag 2 kann nicht bloß
dieselben Werte enthalten wie das Tag 1, das Format ist vielmehr auf
flexible Art aus mehreren Elementen aufgebaut, welche wiederum aus
verschiedenen Feldern bestehen. Die Tag 2 Tabelle zeigt alle Elemente
an, welche in der ausgewählten Datei vorhanden sind.
</para>
<para>
<guibutton>Bearbeiten</guibutton>: Ein Fenster wird geöffnet, in welchem
alle Felder des gewählten Elementes editiert werden können. Wenn mehrere Dateien
ausgewählt sind, so werden die editierten Felder bei allen ausgewählten
Dateien angewendet, welche solch ein Element enthalten.
</para>
<para>
<guibutton>Hinzufügen</guibutton>: Ein Auswahlfenster mit allen
unterstützten Elementtypen wird angezeigt und  ein Element des gewählten
Typs kann editiert und zu der Datei hinzugefügt werden. Dies funktioniert
auch, wenn mehrere Dateien ausgewählt sind; das Element wird dann bei allen
ausgewählten Dateien hinzugefügt.
</para>
<para>
<guibutton>Löschen</guibutton>: Löscht das ausgewählte Element
in den ausgewählten Dateien.
</para>
<para>
<guilabel>Albumcover hierhin ziehen</guilabel> wird angezeigt wenn die Datei
kein Album Cover Bild enthält. Bilder kann man mittels "Drag and Drop" vom
Browser oder Dateimanager hinzufügen; sie werden dann hier angezeigt. Das
Editieren oder Hinzufügen eines Bild-Elements kann mit einem Doppelklick
ausgelöst werden.
</para>

</sect2>

<!--begin manpage ignore-->
<sect2 id="frame-list">
<title>Frame-Liste</title>

<para>
&kid3; kann die meisten Frames aller unterstützten Dateiformate
editieren. Gebräuchliche Frames können über vereinheitlichte Namen
angesprochen werden, so dass sie auch zwischen unterschiedlichen Dateiformaten
ausgetauscht werden können. Frames ohne vereinheitlichte Namen können über die
formatspezifische Bezeichnung erreicht werden.
</para>

<table id="table-frame-list">
  <title>Zuordnung der vereinheitlichten Frame-Namen in den unterschiedlichen Formaten</title>
   <tgroup cols="6">
     <thead>
       <row><entry>Vereinheitlicht</entry>          <entry>ID3v2.3</entry> <entry>ID3v2.4</entry> <entry>MP4</entry>            <entry>ASF</entry>                        <entry>Vorbis</entry></row>
     </thead>
     <tbody>
       <row><entry>Titel</entry>            <entry>TIT2</entry>    <entry>TIT2</entry>    <entry>©nam</entry>           <entry>Title</entry>                      <entry>TITLE</entry></row>
       <row><entry>Interpret</entry>        <entry>TPE1</entry>    <entry>TPE1</entry>    <entry>©ART</entry>           <entry>Author</entry>                     <entry>ARTIST</entry></row>
       <row><entry>Album</entry>            <entry>TALB</entry>    <entry>TALB</entry>    <entry>©alb</entry>           <entry>WM/AlbumTitle</entry>              <entry>ALBUM</entry></row>
       <row><entry>Kommentar</entry>        <entry>COMM</entry>    <entry>COMM</entry>    <entry>©cmt</entry>           <entry>Description</entry>                <entry>COMMENT</entry></row>
       <row><entry>Datum</entry>            <entry>TYER</entry>    <entry>TDRC</entry>    <entry>©day</entry>           <entry>WM/Year</entry>                    <entry>DATE</entry></row>
       <row><entry>Tracknummer</entry>      <entry>TRCK</entry>    <entry>TRCK</entry>    <entry>trkn</entry>           <entry>WM/TrackNumber</entry>             <entry>TRACKNUMBER</entry></row>
       <row><entry>Genre</entry>             <entry>TCON</entry>    <entry>TCON</entry>    <entry>©gen</entry>           <entry>WM/Genre</entry>                   <entry>GENRE</entry></row>
       <row><entry>Albuminterpret</entry>   <entry>TPE2</entry>    <entry>TPE2</entry>    <entry>aART</entry>           <entry>WM/AlbumArtist</entry>             <entry>ALBUMARTIST</entry></row>
       <row><entry>Arrangierung</entry>     <entry>IPLS</entry>    <entry>TIPL</entry>    <entry>ARRANGER</entry>       <entry>WM/Producer</entry>                <entry>ARRANGER</entry></row>
       <row><entry>Autor</entry>            <entry>TOLY</entry>    <entry>TOLY</entry>    <entry>AUTHOR</entry>         <entry></entry>                           <entry>AUTHOR</entry></row>
       <row><entry>BPM</entry>              <entry>TBPM</entry>    <entry>TBPM</entry>    <entry>tmpo</entry>           <entry>WM/BeatsPerMinute</entry>          <entry>BPM</entry></row>
       <row><entry>Katalognummer</entry>    <entry>TXXX:CATALOGNUMBER</entry> <entry>TXXX:CATALOGNUMBER</entry> <entry></entry> <entry></entry>                   <entry>CATALOGNUMBER</entry></row>
       <row><entry>Kompilation</entry>      <entry>TCMP</entry>    <entry>TCMP</entry>    <entry>cpil</entry>           <entry></entry>                           <entry>COMPILATION</entry></row>
       <row><entry>Komponist</entry>        <entry>TCOM</entry>    <entry>TCOM</entry>    <entry>©wrt</entry>           <entry>WM/Composer</entry>                <entry>COMPOSER</entry></row>
       <row><entry>Leiter/Dirigent</entry>  <entry>TPE3</entry>    <entry>TPE3</entry>    <entry>CONDUCTOR</entry>      <entry>WM/Conductor</entry>               <entry>CONDUCTOR</entry></row>
       <row><entry>Copyright</entry>        <entry>TCOP</entry>    <entry>TCOP</entry>    <entry>cprt</entry>           <entry>Copyright</entry>                  <entry>COPYRIGHT</entry></row>
       <row><entry>CD-Nummer</entry>        <entry>TPOS</entry>    <entry>TPOS</entry>    <entry>disk</entry>           <entry>WM/PartOfSet</entry>               <entry>DISCNUMBER</entry></row>
       <row><entry>Kodiert von</entry>      <entry>TENC</entry>    <entry>TENC</entry>    <entry>©enc</entry>           <entry>WM/EncodedBy</entry>               <entry>ENCODED-BY</entry></row>
       <row><entry>Kodierungseinstellungen</entry> <entry>TSSE</entry> <entry>TSSE</entry> <entry>©too</entry>          <entry>WM/EncodingSettings</entry>        <entry>ENCODERSETTINGS</entry></row>
       <row><entry>Kodierdatum</entry>      <entry></entry>        <entry>TDEN</entry>    <entry></entry>               <entry>WM/EncodingTime</entry>            <entry>ENCODINGTIME</entry></row>
       <row><entry>Werk</entry>             <entry>TIT1</entry>    <entry>TIT1</entry>    <entry>©grp</entry>           <entry>WM/ContentGroupDescription</entry> <entry>GROUPING</entry></row>
       <row><entry>Anfangstonart</entry>    <entry>TKEY</entry>    <entry>TKEY</entry>    <entry></entry>               <entry>WM/InitialKey</entry>              <entry>INITIALKEY</entry></row>
       <row><entry>ISRC</entry>             <entry>TSRC</entry>    <entry>TSRC</entry>    <entry>ISRC</entry>           <entry>WM/ISRC</entry>                    <entry>ISRC</entry></row>
       <row><entry>Sprache</entry>          <entry>TLAN</entry>    <entry>TLAN</entry>    <entry>LANGUAGE</entry>       <entry>WM/Language</entry>                <entry>LANGUAGE</entry></row>
       <row><entry>Texter</entry>           <entry>TEXT</entry>    <entry>TEXT</entry>    <entry>LYRICIST</entry>       <entry>WM/Writer</entry>                  <entry>LYRICIST</entry></row>
       <row><entry>Text</entry>             <entry>USLT</entry>    <entry>USLT</entry>    <entry>©lyr</entry>           <entry>WM/Lyrics</entry>                  <entry>LYRICS</entry></row>
       <row><entry>Medium</entry>           <entry>TMED</entry>    <entry>TMED</entry>    <entry>SOURCEMEDIA</entry>    <entry></entry>                           <entry>SOURCEMEDIA</entry></row>
       <row><entry>Stimmung</entry>         <entry></entry>        <entry>TMOO</entry>    <entry></entry>               <entry>WM/Mood</entry>                    <entry>MOOD</entry></row>
       <row><entry>Originalalbum</entry>    <entry>TOAL</entry>    <entry>TOAL</entry>    <entry>ORIGINALALBUM</entry>  <entry>WM/OriginalAlbumTitle</entry>      <entry>ORIGINALALBUM</entry></row>
       <row><entry>Originalkünstler</entry> <entry>TOPE</entry>    <entry>TOPE</entry>    <entry>ORIGINALARTIST</entry> <entry>WM/OriginalArtist</entry>          <entry>ORIGINALARTIST</entry></row>
       <row><entry>Originaldatum</entry>    <entry>TORY</entry>    <entry>TDOR</entry>    <entry>ORIGINALDATE</entry>   <entry>WM/OriginalReleaseYear</entry>     <entry>ORIGINALDATE</entry></row>
       <row><entry>Teil</entry>             <entry></entry>        <entry>TSST</entry>    <entry>PART</entry>           <entry>WM/SubTitleDescription</entry>     <entry>PART</entry></row>
       <row><entry>Musiker</entry>          <entry>IPLS</entry>    <entry>TMCL</entry>    <entry>PERFORMER</entry>      <entry></entry>                           <entry>PERFORMER</entry></row>
       <row><entry>Bild</entry>             <entry>APIC</entry>    <entry>APIC</entry>    <entry>covr</entry>           <entry>WM/Picture</entry>                 <entry>METADATA_BLOCK_PICTURE</entry></row>
       <row><entry>Herausgeber</entry>      <entry>TPUB</entry>    <entry>TPUB</entry>    <entry>PUBLISHER</entry>      <entry>WM/Publisher</entry>               <entry>PUBLISHER</entry></row>
       <row><entry>Veröffentlichungsland</entry> <entry>TXXX:RELEASECOUNTRY</entry> <entry>TXXX:RELEASECOUNTRY</entry>  <entry></entry> <entry></entry>           <entry>RELEASECOUNTRY</entry></row>
       <row><entry>Remixer</entry>          <entry>TPE4</entry>    <entry>TPE4</entry>    <entry>REMIXER</entry>        <entry>WM/ModifiedBy</entry>              <entry>REMIXER</entry></row>
       <row><entry>Sortiername des Albums</entry> <entry>TSOA</entry> <entry>TSOA</entry> <entry>soal</entry>           <entry>WM/AlbumSortOrder</entry>          <entry>ALBUMSORT</entry></row>
       <row><entry>Sortiername des Albuminterpreten</entry> <entry>TSO2</entry>  <entry>TSO2</entry> <entry>soaa</entry> <entry></entry>                          <entry>ALBUMARTISTSORT</entry></row>
       <row><entry>Sortiername des Interpreten</entry> <entry>TSOP</entry> <entry>TSOP</entry> <entry>soar</entry>      <entry>WM/ArtistSortOrder</entry>         <entry>ARTISTSORT</entry></row>
       <row><entry>Sortiername des Komponisten</entry> <entry>TSOC</entry> <entry>TSOC</entry> <entry>soco</entry>      <entry></entry>                           <entry>COMPOSERSORT</entry></row>
       <row><entry>Sortiername des Titels</entry> <entry>TSOT</entry> <entry>TSOT</entry> <entry>sonm</entry>           <entry>WM/TitleSortOrder</entry>          <entry>TITLESORT</entry></row>
       <row><entry>Untertitel</entry>       <entry>TIT3</entry>    <entry>TIT3</entry>    <entry>SUBTITLE</entry>       <entry>WM/SubTitle</entry>                <entry>SUBTITLE</entry></row>
       <row><entry>Webseite</entry>         <entry>WOAR</entry>    <entry>WOAR</entry>    <entry>WEBSITE</entry>        <entry>WM/AuthorURL</entry>               <entry>WEBSITE</entry></row>
       <row><entry>WWW Audio-Datei</entry>  <entry>WOAF</entry>    <entry>WOAF</entry>    <entry></entry>               <entry>WM/AudioFileURL</entry>            <entry>WWWAUDIOFILE</entry></row>
       <row><entry>WWW Audio-Quelle</entry> <entry>WOAS</entry>    <entry>WOAS</entry>    <entry></entry>               <entry>WM/AudioSourceURL</entry>          <entry>WWWAUDIOSOURCE</entry></row>
     </tbody>
   </tgroup>
 </table>

<para>
Bemerkungen zu den Zuordnungen der vereinheitlichten Frame-Namen:
<itemizedlist>
<listitem><para>
Die Zahl der vereinheitlichten Frame-Namen ist insofern beschränkt, als dass
in allen unterstützten Dateiformaten eine sinnvolle Zuordnung möglich sein
soll. Die meisten Tags unterstützen Frames mit beliebigen Namen; diese werden
dann verwendet, wenn kein spezifisches Frame zur Verfügung steht (z.B. die
Namen in Großbuchstaben in der Spalte MP4). Falls keine solche Möglichkeit
besteht, so kann es vorkommen, dass für ein Format bestimmte Frame-Typen nicht
unterstützt werden können, so Autor und Musiker für ASF (WMA).
</para></listitem>
<listitem><para>
Die Zuordnungen sind nicht rein willkürlich, sondern orientieren sich daran,
wie die Frames in anderen Programmen und Geräten verwendet werden. So legt das
ID3v2-Frame "TPE2 - Band/Orchester/Begleitung" nicht unbedingt die Verwendung
als Albuminterpret nahe, doch ist dies die gebräuchlichste Verwendung. Die
eigentliche Bedeutung bei ID3v2 ist dann wiederum der Grund, wieso dieses
Frame beim Importieren (z.B. von Discogs) für das Orchester verwendet wird,
obwohl dies für andere Tag-Formate etwas sonderbar erscheinen mag.
</para></listitem>
<listitem><para>
Die Zuordnung ist nicht immer eindeutig. So wird bei ID3v2.3 sowohl für
Arrangierung als auch für Musiker ein IPLS-Frame verwendet. Beim Zurücklesen
wird dann für beide Typen "Arrangierung" angezeigt.
</para></listitem>
<listitem><para>
Die Frames Arrangierung und Musiker verwenden ein besonderes Format für
ihren Inhalt: "Mitwirkung 1|Mitwirkender 1|Mitwirkung 2|Mitwirkender 2|...",
beispielsweise "Chorus Master|Ernst Dunshirn|Soprano Vocals|Anna
Netrebko". Dadurch wird für die IPLS bzw. TIPL/TMCL Frames in MP3-Dateien eine
Zeichenkettenliste mit dem spezifizierten Inhalt erzeugt (das "|" dient als
Trennzeichen zwischen den einzelnen Zeichenketten). Entsprechende Werte werden
auch beim Import von Daten von Servern, welche diese Informationen bieten,
gesetzt.
</para></listitem>
</itemizedlist>
</para>

</sect2>
<!--end manpage ignore-->

<sect2>
<title>Synchronisierter Text und Ereignis-Zeitcodes</title>

<para>
Für zeitlich mit den Audio-Daten synchronisierte Informationen steht ein
spezieller Editor zur Verfügung. Diese Frames sind für ID3v2.3.0 und ID3v2.4.0
Tags unterstützt. Um ein solches Frame zu erstellen, muss in der Liste, welche
nach Klick auf <guibutton>Hinzufügen</guibutton> erscheint, sein Name
ausgewählt werden - <guilabel>Synchronisierter Text</guilabel> oder
<guilabel>Ereignis-Zeitcodes</guilabel>. Beide Frame-Typen werden in
einem gleichartigen Editor bearbeitet, bei den Ereignis-Zeitcodes kann aus
einer Menge vordefinierter Codes ausgewählt werden, während beim
synchronisierten Text der Liedtext eingegeben werden muss. Im folgenden wird
die Eingabe von synchronisiertem Text erklärt.
</para>
<para>
Eine Datei, welche ein ID3v2 Tag enthält, wird selektiert und der Editor wird
mit <guibutton>Hinzufügen</guibutton> und Auswahl von <guilabel>
Synchronisierter Text</guilabel> geöffnet. Falls das Synchronisierter Text Frame schon
existiert, wird es selektiert und auf <guibutton>Bearbeiten</guibutton>
geklickt. Die Werkzeugleiste zum Abspielen von Audio-Dateien wird automatisch
geöffnet, so dass das aktuelle Stück abgespielt und angehalten werden kann, um
die Texte zu synchronisieren.
</para>
<para>
Die Einstellungen im oberen Teil des SYLT Editors müssen normalerweise nicht
verändert werden. Wenn der Text Zeichen enthält, welche nicht im Latin 1
Zeichensatz enthalten sind, so kann die Textkodierung auf UTF16 (oder UTF8 für
ID3v2.4.0) umgestellt werden. Für englischsprachige Texte und maximale
Kompatibilität sollte ISO-8859-1 verwendet werden.
</para>
<para>
Der Abschnitt <guilabel>Text</guilabel> hat fünf Knöpfe oberhalb der Tabelle.
<guibutton>Hinzufügen</guibutton> erstellt einen neuen Ereigniseintrag in der
Tabelle. Die Zeit wird von der momentanen Position der Wiedergabe genommen, so
dass ein Eintrag für die aktuelle Stelle des abgespielten Stücks erzeugt wird.
Die Einträge in der Tabelle müssen zeitlich geordnet sein, die neue Zeile wird
daher entsprechend eingeordnet. Einträge mit ungültiger Zeit werden speziell
behandelt: Wenn die aktuelle Zeile eine ungültige Zeit hat, so wird ihre Zeit
durch die Wiedergabezeit ersetzt, und es wird keine neue Zeile hinzugefügt.
Wenn die Zeit nicht ungültig ist, so wird die erste Zeile mit einer ungültigen
Zeit genommen, falls eine solche vorhanden ist. Dieses Verhalten sollte es
erleichtern, die Zeit-Spalte auszufüllen, wenn der Text bereits in der Tabelle
vorhanden ist, aber die Zeiten noch fehlen (was der Fall ist, wenn 
unsynchronisierte Texte importiert werden). Man beachte, dass ungültige Zeiten
mit 00:00.00 dargestellt werden, also gleich wie die Zeit ganz zu Beginn des
Stücks, welche nicht ungültig ist. Um einen Zeiteintrag ungültig zu machen,
kann die <keysym>Delete</keysym> Taste gedrückt werden oder
<guimenu>Löschen</guimenu> aus dem Kontextmenü verwendet werden. Neue Zeilen,
welche mit <guimenu>Zeile einfügen</guimenu> des Kontextmenüs oder durch
<guibutton>Importieren</guibutton> bzw. <guibutton>Von
Zwischenablage</guibutton> erstellt werden, enthalten ebenfalls ungültige
Zeiten. Zeilen in der Tabelle können mit Klick auf
<guibutton>Löschen</guibutton> oder dem <guimenu>Zeilen entfernen</guimenu>
Kontextmenü gelöscht werden.
</para>
<para>
Synchronisierter Liedtext kann aus einer Datei importiert werden mit
<guibutton>Importieren</guibutton>. Als Dateiformat wird LRC (einfach oder
erweitert) erwartet. Wenn die ausgewählte Datei keine eckige Klammer in der
ersten Zeile enthält, so wird angenommen, dass es sich um eine einfache
Textdatei mit unsynchronisiertem Liedtext handelt. Die Zeilen einer solchen
Datei werden dann in die Text-Spalte importiert und die Zeit-Spalte enthält
ungültige Zeiten. Die Zeitinformationen können mit Hilfe des
<guibutton>Hinzufügen</guibutton>-Knopfs ergänzt oder manuell erfasst
werden. Es ist auch möglich, Liedtexte mittels Kopieren und Einfügen zu
importieren (<guilabel>Von
Zwischenablage</guilabel>). <guibutton>Exportieren</guibutton> erlaubt es,
synchronisierten Text in eine LRC-Datei zu schreiben. Man beachte, dass nur
Einträge mit gültiger Zeit exportiert werden, und dass die Einträge zeitlich
sortiert werden. Einträge mit ungültiger Zeit werden auch nicht in das
SYLT-Frame geschrieben, man sollte daher alle Zeitinformationen eintragen,
bevor man den Editor verlässt.
</para>
<para>
Die <ulink url="http://id3.org/id3v2.4.0-frames">ID3 Spezifikation</ulink>
legt es nahe, Zeitstempel für jede Silbe zu erfassen. Die meisten Player
unterstützen jedoch bloß eine Granularität von einer Zeile bzw. einem
Satz. Um beide Anwendungsfälle zu unterstützen, folgt &kid3; denselben
Konventionen wie <ulink
url="http://www.compuphase.com/software_sylteditor.htm">SYLT
Editor</ulink>. Es wird angenommen, dass Text, welcher in der Tabelle
eingetragen wird, eine neue Zeile startet, es sei denn, er beginnt mit einem
Leerzeichen oder Bindestrich. Diese Regel kann außer Kraft gesetzt werden,
indem man den Text mit einem Unterstrich ('_') beginnen lässt, um eine
Fortsetzung der Zeile zu erzwingen, bzw. mit einem Doppelkreuz ('#') um eine
neue Zeile auch dann zu erhalten, wenn diese mit einem Leerzeichen oder
Bindestrich beginnt. Diese Umschaltzeichen werden nicht im SYLT-Frame
gespeichert. Innerhalb des Frames beginnen neue Zeilen mit einem Zeilenumbruch
(das Zeichen mit Hex-Code 0A), ansonsten handelt es sich um eine Fortsetzung
der Zeile. Beim Lesen existierender SYLT-Frames prüft &kid3;, ob der erste Text
mit einem Zeilenumbruch beginnt. Ist dies nicht der Fall, so wird angenommen,
dass alle Texte separate Zeilen sind und keine Silbenfortsetzungen verwendet
werden.
</para>
<para>
Während dem Abspielen einer Datei wird die aktuelle Zeile hervorgehoben, so
dass die Korrektheit der Synchronisationsinformation überprüft werden
kann. Existiert ein Versatz, so kann er mit dem Kontextmenü
<guimenu>Zeitabstand hinzufügen</guimenu> korrigiert werden, wobei negative
Werte die Zeit reduzieren. Die Funktion <guimenu>Zur Position
springen</guimenu> ermöglicht es, die Position der Wiedergabe an die Zeit
der ausgewählten Zeile zu setzen.
</para>
</sect2>

</sect1>

<sect1 id="file-menu">
<title>Das Menü Datei</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>O</keycap></keycombo>
</shortcut>
<guimenu>Datei</guimenu>
<guimenuitem>Öffnen...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Ein Verzeichnis wird geöffnet</action>, und alle Dateien,
welche den gewählten Dateinamenfilter erfüllen, werden im Dateilistenfeld
angezeigt. Die gewählte Datei wird selektiert.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Zuletzt geöffnete Dateien</guimenuitem>
</menuchoice></term>
<listitem><para><action>Ein kürzlich geöffnetes Verzeichnis wird geöffnet.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>D</keycap></keycombo>
</shortcut>
<guimenu>Datei</guimenu>
<guimenuitem>Verzeichnis öffnen...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Ein Verzeichnis wird geöffnet</action>, und alle Dateien,
welche den gewählten Dateinamenfilter erfüllen, werden im Dateilistenfeld
angezeigt.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
</shortcut>
<guimenu>Datei</guimenu>
<guimenuitem>Speichern</guimenuitem>
</menuchoice></term>
<listitem><para><action>Speichert alle veränderten Dateien im Verzeichnis.</action>
Die veränderten Dateien sind durch ein Diskettensymbol gekennzeichnet. Wenn
Dateinamen verändert wurden, so werden die entsprechenden Dateien
umbenannt.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Zuletzt gespeicherte Fassung</guimenuitem>
</menuchoice></term>
<listitem><para><action>Macht die Änderungen an einer oder mehreren Dateien
rückgängig.</action> Wenn keine Dateien im Dateilistenfeld selektiert sind, so
werden die Änderungen an allen Dateien rückgängig gemacht, ansonsten nur an
den ausgewählten Dateien.</para></listitem>
</varlistentry>

<varlistentry id="import">
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Importieren...</guimenuitem>
</menuchoice></term>
<listitem><para>Der <action>Import Dialog</action> wird verwendet, um Daten
direkt von einem freedb.org Server, von einem MusicBrainz Server,
von Discogs, Amazon oder anderen Quellen mit Albumtitellisten zu importieren.
</para>
<para id="import-freedb">
Zum Importieren von einem freedb.org Server wird <guibutton>Von Server:</guibutton>
<guibutton>gnudb.org</guibutton> oder <guibutton>TrackType.org</guibutton>
gewählt. Der zu suchende Interpret und der Name
des Albums können in den zwei oberen Feldern eingegeben werden,
und die gefundenen Alben werden nach
Klick auf <guibutton>Suchen</guibutton> dargestellt, sobald sie von <ulink
url="http://www.gnudb.org">www.gnudb.org</ulink> empfangen werden.
Die Track Daten eines Albums
werden nach Auswahl geladen, der verwendete freedb.org Server kann
gewählt werden, ebenso der CGI Pfad. Die
importierten Daten werden in der Vorschau des Import Dialogfensters
dargestellt. Wenn man mit den Daten in der Vorschau zufrieden ist,
können sie mit <guibutton>OK</guibutton> importiert werden.
</para>
<para id="import-discogs">
Zum Importieren vom Discogs Server wird <guibutton>Discogs</guibutton>
gewählt. Wie bei <guibutton>Von
gnudb.org</guibutton> können auch hier Artist und Album eingegeben werden und
es wird ebenfalls eine Liste mit Alben zur Auswahl gestellt.
Wenn <guilabel>Standard Tags</guilabel> markiert ist, werden grundlegende
Informationen importiert, so z.B. Interpret, Album und Titel.
Wenn <guilabel>Zusätzliche Tags</guilabel> markiert ist, werden mehr
verfügbare Informationen importiert, z.B. Musiker, Arrangierer oder der
Herausgeber.
Wenn <guilabel>Cover-Bilder</guilabel> markiert ist, werden Cover-Bilder
heruntergeladen, falls vorhanden.
</para>
<para id="import-amazon">
Zum Importieren von Amazon wird <guibutton>Amazon</guibutton>
gewählt. Wie bei <guibutton>Von
gnudb.org</guibutton> können auch hier Artist und Album eingegeben werden und
es wird ebenfalls eine Liste mit Alben zur Auswahl gestellt.
Wenn <guilabel>Zusätzliche Tags</guilabel> markiert ist, werden mehr
verfügbare Informationen importiert, z.B. Musiker, Arrangierer oder der
Herausgeber.
Wenn <guilabel>Cover-Bilder</guilabel> markiert ist, werden Cover-Bilder
heruntergeladen, falls vorhanden.
</para>
<para id="import-musicbrainzrelease">
In der gleichen Art kann mit <guibutton>Von MusicBrainz Album</guibutton>
auch in der Album-Datenbank von MusicBrainz gesucht
werden. Die Bedienung ist wie bei <guibutton>gnudb.org</guibutton>
beschrieben.
</para>
<para id="import-musicbrainz">
Zum Importieren von einem MusicBrainz Server dient der Dialog, der nach
Klicken auf <guibutton>Von MusicBrainz Fingerprint</guibutton> erscheint. Wie bei freedb
kann auch hier der Server ausgewählt werden. Unten ist eine Tabelle,
welche die importierten Track Daten darstellt. Die rechte Spalte zeigt dabei
den Zustand der MusicBrainz-Abfrage, welche gleich mit dem Öffnen des Dialogs
mit "Suche läuft" beginnt. Es folgen dann ein Abfrage des Fingerprints und,
falls diese kein Ergebnis liefert, eine Suche anhand der in der Datei
vorhandenen Tags. Für eine erfolgreiche MusicBrainz-Suche kann es daher
hilfreich sein, vorhandene Informationen (z.B. Interpret und Album) vorangehend
in den Tags zu speichern. Wenn ein Resultat gefunden wurde, so endet die Suche
im Zustand "Erkannt", andernfalls wurde nichts gefunden oder gleich mehrere
mögliche Resultate, von den der Benutzer eines auswählen kann.
<guibutton>OK</guibutton> und <guibutton>Anwenden</guibutton> übernehmen die
importierten Daten, <guibutton>Abbrechen</guibutton> schließt den
Dialog. Das Schließen des Dialogs kann eine Weile dauern, da noch die ganze
MusicBrainz-Maschinerie runtergefahren werden muss.
</para>

<para id="import-text">
Zum Importieren von Albumdaten in Textform öffnet man einen Unterdialog
mit <guibutton>Von Datei/Zwischenablage</guibutton>.
Dort stehen mehrere vorkonfigurierte
Formate zur Verfügung. Die ersten zwei, "CSV unquoted" und "CSV quoted",
dienen dazu, Daten welche über die Export Funktion exportiert wurden, wieder
zu importieren. Diese Daten können natürlich von einer Tabellenkalkulation
bearbeitet werden. CSV-Daten aus einer Tabellenkalkulation müssen mit
Tabulator als Trennzeichen geschrieben werden und sollten sich über "CSV
quoted" einlesen lassen. Dieses ist flexibler als "CSV unquoted", dafür dürfen
die enthaltenen Felder keine Anführungszeichen enthalten. Falls nur von &kid3;
exportiert und wieder importiert wird, so sollte dies problemlos mit "CSV
unquoted" möglich sein. Im Kontextmenü der Dateiliste hat es darüber hinaus
die Funktionen "Export CSV" und "Import CSV", welche Skripts benutzen, um
CSV-Daten vollständiger und flexibler auszutauschen.
</para>

<para>
Das nächste Format, "freedb HTML
text", kann benutzt werden, um Informationen aus einer HTML-Seite von
<ulink url="http://freedb.org">freedb.org</ulink> zu kopieren. Dazu sucht man
sich in freedb das Album, und wenn die gewünschte Information im Browser
angezeigt wird, kann sie selektiert und in die Zwischenablage kopiert
werden. Nach einem Klick auf <guibutton>Von Zwischenablage</guibutton> werden
die importierten Daten in der Tabelle angezeigt und können mit
<guibutton>OK</guibutton> übernommen werden. Das Ziel
(<guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel> oder
<guilabel>Tag 1 und Tag 2</guilabel>) kann mit einem
Auswahlfeld festgelegt werden. Die Titel in der Dateiliste sollten in der
korrekten Reihenfolge angezeigt sein um die richtigen Tags zu kriegen. Dies
ist kein Problem, wenn sie nummeriert sind.
</para>
<para>
Das nächste vorkonfigurierte Format, "freedb HTML source", kann dann benutzt
werden, wenn die Import-Daten als HTML-Dokument vorliegen. Solch eine Datei
kann im Datei Dialog, welcher nach Klick auf <guibutton>Von
Datei</guibutton> erscheint, ausgewählt werden. Natürlich können die Daten auch
in einem Editor kopiert und dann über die Zwischenablage übernommen
werden. Dieses Format kann für Offline Import nützlich sein, obschon die
HTML-Datei auch von einem Browser angezeigt und im ersten Format über
die Zwischenablage importiert werden kann.
</para>
<para>
Weitere vorkonfigurierte Formate, z.B. "Track Title Time" stehen zur
Verfügung. Mit Klick auf <guibutton>Hinzufügen</guibutton> kann ein leeres
benutzerdefiniertes Format erzeugt und vom Benutzer gesetzt
werden. Die zwei Zeilen unterhalb des Formatnamens können hierzu mit regulären
Ausdrücken gefüllt werden. Der erste Ausdruck wird einmal angewendet, um
albumspezifische Daten wie Interpret, Album, Jahr und Genre zu extrahieren. Die
zweite Zeile wird vom Dokumentanfang bis zum Schluss für jeden Titel probiert,
um Titeldaten zu kriegen, also Nummer und Titel. In den regulären Ausdrücken
können alle von Qt unterstützten Funktionen eingesetzt werden; also das meiste
von dem, was Perl bietet. Klammerkonstrukte "(..)" werden benützt, um
Felddaten zu extrahieren und werden von einem &kid3;-spezifischen Feldcode
eingeleitet. Die Codes sind dieselben wie beim Dateinamenformat, auch hier
sind nebst den unten aufgelisteten Codes beliebige Framenamen möglich:
</para>

<para id="format-codes">
<itemizedlist>
<listitem><para>%s %{title} Titel (Song)</para></listitem>
<listitem><para>%a %{artist} Interpret (Artist)</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Kommentar (Comment)</para></listitem>
<listitem><para>%y %{year} Jahr (Year)</para></listitem>
<listitem><para>%t %{track} Nummer (Track)</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%d %{duration} Länge (Dauer)</para></listitem>
</itemizedlist>
</para>

<para>
Beispiel: Ein regulärer Ausdruck für die zweite Zeile, um Titel aus einer .m3u
Stückliste zu holen, könnte "%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]"
sein. Alle Formate können geändert werden, indem der Name und die regulären
Ausdrücke editiert werden und <guibutton>Einstellungen speichern</guibutton>
gedrückt wird. Gespeichert werden sie in der Datei <filename>kid3rc</filename>
im Konfigurationsverzeichnis. Diese Datei kann auch direkt verändert werden,
um mehr Importformate zu haben, oder man kann sie löschen, um wieder zu den
Standardeinstellungen zu kommen. Formate können
mit <guibutton>Entfernen</guibutton> gelöscht werden.
</para>
<para>
<guibutton>Genauigkeit</guibutton> zeigt eine Abschätzung, wie gut die
importierten Daten zu den Stücken passen. Dazu werden die Längen oder die
Dateinamen verglichen um den Grad an Übereinstimmung in Prozent zu
errechnen.
<guibutton>Cover-Bild</guibutton> zeigt die URL des Cover-Bildes, welches
heruntergeladen wird.
</para>
<para>
Um zu prüfen, ob die importierten Stücke den vorhandenen Dateien entsprechen,
können die Längen verglichen werden. Diese Option kann mit dem Markierungsfeld
<guibutton>Teste maximal erlaubten Zeitunterschied</guibutton> eingeschaltet
werden und der maximal erlaubten Zeitunterschied kann in Sekunden eingestellt
werden. Wird eine Überschreitung dieser Toleranzschwelle festgestellt,
so wird die entsprechende Länge in der Vorschau rot dargestellt.
</para>
<para>
Falls nun die vorhandenen Dateien in einer anderen Reihenfolge als die
importierten Stücke vorliegen, so sollte die Zuordnung korrigiert
werden. Diese Arbeit wird durch die <guilabel>Zuordnen mit</guilabel>
Knöpfe <guibutton>Länge</guibutton>, <guibutton>Nummer</guibutton>
und <guibutton>Titel</guibutton> erleichtert, welche die Stücke dem jeweiligen
Feld entsprechend zuordnen. Sollte die Zuordnung noch manuell korrigiert
werden müssen, so kann ein Track nach Drücken der Steuerungs-Taste
(<keycap>Ctrl</keycap>/<keycap>Strg</keycap>) mit der linken Maustaste gefasst
und dann an die gewünschte Stelle gezogen werden.
</para>
<para>
Wenn der Import Dialog geöffnet wird, enthält die Tabelle die aktuell
vorhandenen Werte der Tags. Der Tag Typ (Tag 1, Tag 2, Tag 1 und Tag 2) kann
über das <guilabel>Ziel</guilabel> Auswahlfeld selektiert werden. Der Knopf
rechts von diesem Auswahlfeld dient dazu, die Tabelle auf die in den Tags
gespeicherten Werte zurückzusetzen. Über die Markierungsfelder in der ersten
Tabellenspalte können die Stücke gewählt werden, deren Tags importiert werden
sollen. Dies kann z.B. dann nützlich sein, wenn ein Verzeichnis alle Stücke
eines Doppelalbums enthält, aber bloß die Stücke der zweiten CD importiert
werden sollen.
</para>
<para>
Um die Dateien, welche importiert werden, zu identifizieren, können die
Dateinamen oder die vollständigen Pfade in der Tabelle dargestellt
werden. Diese Einstellung ist über das Kontextmenü, welches bei Rechtsklick
auf die Kopfzeile erscheint, möglich. Die Werte in der Import-Tabelle lassen
sich editieren. Die momentan in den Tags vorhandenen Werte lassen sich mit dem
Rückgängig-Knopf rechts vom <guilabel>Ziel</guilabel>-Listenfeld
wiederherstellen. Dies ist auch dann nützlich, wenn man
das <guilabel>Ziel</guilabel> verändert hat und die dort vorhandenen Werte in
der Tabelle sehen möchte.
</para>
<para>
Wie in fast allen Dialogen dient der <guibutton>Einstellungen
speichern</guibutton> Knopf dazu, die dialogspezifischen Optionen und die
Fenstergröße persistent zu speichern.
</para>

<para id="import-tags">
<guibutton>Von Tags</guibutton> führt zu einem Unterdialog, mit welchem sich
Tag Frames mit dem Inhalt aus anderen Tag Frames füllen lassen. Dies kann
dazu benutzt werden, um einfach Informationen zwischen Tags zu kopieren
oder einen Teil des Inhaltes eines Tag Frames zu extrahieren und in einem
anderen Tag Frame einzufügen.
</para>
<para>
Wie beim <link linkend="import-text">Import von Datei/Clipboard</link>
stehen frei konfigurierbare Formate zur Verfügung, um verschiedene Operationen
durchzuführen. Vorkonfigurierte Formate erlauben es beispielsweise, den Wert
des Interpreten zum Album Interpreten, Komponisten oder Leiter zu kopieren,
bei Titeln, welche die Tracknummer enthalten, diese zu extrahieren und im
Tracknummer-Frame zu speichern. Ebenso lässt sich ein Untertitel aus dem
Titel extrahieren.
</para>
<para>
Das Erstellen eines eigenen Importformates wird im folgenden anhand eines
Beispieles erklärt. Die Information im Untertitel soll auch im Kommentar
gesetzt werden. Dazu wird ein neues Format mit <guibutton>Hinzufügen</guibutton>
erstellt und ein neuer Name gesetzt, in diesem Beispiel also "Subtitle to
Comment". Nun gibt man unter <guilabel>Quelle</guilabel> "%{subtitle}" und
unter <guilabel>Ermittlung</guilabel> "%{comment}(.*)" ein und
klickt <guibutton>Einstellungen speichern</guibutton>.
</para>
<para>
Der Ausdruck in <guilabel>Quelle</guilabel> kann aus
<link linkend="format-codes">Format Codes</link> für beliebige Tag Frames
bestehen, wobei natürlich auch mehrere Codes verwendet werden können, um den
Inhalt verschiedener Frames zu kombinieren. Für jeden Track wird aus den Tags
und dem <guilabel>Quelle</guilabel> Format ein Text erzeugt, und auf diesen
wird dann der reguläre Ausdruck aus <guilabel>Ermittlung</guilabel>
angewendet, um neue Tag Werte zu setzen. Dieser reguläre Ausdruck enthält
Klammerkonstrukte "(..)", um Felddaten zu extrahieren, und die
Klammer-Konstrukte werden vom Format Code des Tag Frames eingeleitet. Es
funktioniert also gleich wie bei den Formaten
zum <link linkend="import-text">Import von Datei/Clipboard
</link>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Importieren von gnudb.org...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Importieren von einem freedb.org Server
mit Album-Suche auf gnudb.org.</action>
Dieser Menüpunkt öffnet denselben Import Dialog
wie <guimenuitem>Importieren...</guimenuitem>, öffnet jedoch direkt auch
den <guibutton>gnudb.org</guibutton> Dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Importieren von TrackType.org...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Importieren vom TrackType.org Server.</action>
Dieser Menüpunkt öffnet denselben Import Dialog
wie <guimenuitem>Importieren...</guimenuitem>, öffnet jedoch direkt auch
den <guibutton>TrackType.org</guibutton> Dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Importieren von Discogs...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Importieren vom Discogs Server.</action>
Dieser Menüpunkt öffnet denselben Import Dialog
wie <guimenuitem>Importieren...</guimenuitem>, öffnet jedoch direkt auch
den <guibutton>Discogs</guibutton> Dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Importieren von Amazon...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Importieren von Amazon.</action>
Dieser Menüpunkt öffnet denselben Import Dialog
wie <guimenuitem>Importieren...</guimenuitem>, öffnet jedoch direkt auch
den <guibutton>Amazon</guibutton> Dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Importieren von MusicBrainz Album...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Importieren von der MusicBrainz Album Datenbank.</action>
Dieser Menüpunkt öffnet denselben Import Dialog
wie <guimenuitem>Importieren...</guimenuitem>, öffnet jedoch direkt auch
den <guibutton>Von MusicBrainz Album</guibutton> Dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Importieren von MusicBrainz Fingerprint...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Importieren von einem MusicBrainz Server.</action>
Dieser Menüpunkt öffnet denselben Import Dialog
wie <guimenuitem>Importieren...</guimenuitem>, öffnet jedoch direkt auch
den <guibutton>Von MusicBrainz Fingerprint</guibutton> Dialog.</para></listitem>
</varlistentry>

<varlistentry id="batch-import">
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Automatisch importieren...</guimenuitem>
</menuchoice></term>
<listitem><para>
<action>Automatisch importieren</action> lassen sich Informationen für mehrere
Alben von verschiedenen Web-Diensten. Wenn Verzeichnisse in der Dateiliste
selektiert sind, so werden Metadaten für die Stücke der gewählten
Verzeichnisse importiert. Wenn kein Verzeichnis ausgewählt ist, so werden
Informationen für alle Verzeichnisse innerhalb der Dateiliste importiert.
</para>
<para>
Der Tag Typ (Tag 1, Tag 2, Tag 1 und Tag 2) kann
über das <guilabel>Ziel</guilabel> Auswahlfeld selektiert werden.
</para>
<para>
Profile bestimmen, von welchen Servern die Album-Informationen geholt
werden. Einige Profile sind bereits vordefiniert (All, MusicBrainz, Discogs,
Cover Art), eigene Profile können mit dem <guibutton>Hinzufügen</guibutton>
Knopf rechts von der <guilabel>Profil</guilabel> Auswahlliste erstellt
werden.
</para>
<para>
Die Tabelle darunter zeigt die Server, welche benutzt werden, wenn mit dem
ausgewählten Profil importiert wird. Der Import-Prozess für ein Album wird
beendet, wenn alle geforderten Informationen gefunden wurden, daher ist die
Reihenfolge der Server in der Tabelle wichtig. Sie kann mit den
<guibutton>Nach oben</guibutton> und <guibutton>Nach unten</guibutton>
Knöpfen verändert werden. Mit <guibutton>Bearbeiten</guibutton> kann ein
bestehender Eintrag verändert werden. Die <guibutton>Server</guibutton>
Auswahl stellt dieselben Server zur Verfügung wie die Import-Funktionen.
<guilabel>Standard Tags</guilabel>,
<guilabel>Zusätzliche Tags</guilabel>
und <guilabel>Cover-Bilder</guilabel> bestimmen die Informationen, welche
vom Server geholt werden sollen. Die <guilabel>Genauigkeit</guilabel>
schließlich bestimmt die minimale Übereinstimmung, welche erreicht werden
muss, damit die importierten Daten akzeptiert werden. Ist sie ungenügend, so
wird ein Import mit dem nächsten Server versucht. Dieser Dialog mit den
Server-Eigenschaften wird auch angezeigt wenn
<guibutton>Hinzufügen</guibutton> gewählt wird, um einen neuen Eintrag zu
erstellen. Bestehende Zeilen können mit <guibutton>Entfernen</guibutton>
gelöscht werden.
</para>
<para>
Um einen automatischen Import mit dem ausgewählten Profil zu beginnen wird
<guibutton>Starten</guibutton> gedrückt. Details über den laufenden Prozess
werden im Dialog oben angezeigt. <guibutton>Abbrechen</guibutton> führt zu
einer vorzeitigen Beendigung des Imports.
</para>
<para>
</para></listitem>
</varlistentry>

<varlistentry id="browse_pictures">
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Nach Cover-Bildern suchen...</guimenuitem>
</menuchoice></term>
<listitem>
<para>
Der Dialog <action>Nach Cover-Bildern suchen</action> hilft bei der Suche nach
Album Cover-Bildern. <guilabel>Interpret/Album</guilabel> werden wenn möglich
aus den Tags übernommen. <guilabel>Quelle</guilabel> stellt eine Vielzahl von
Websites mit Cover-Bildern zur Verfügung. Unter dem Namen ist die URL mit
Interpret und Album als Parametern angegeben. Für URL-codierte Werte können
dabei <userinput>%u{artist}</userinput> und <userinput>%u{album}</userinput>
angegeben werden oder auch andere Werte aus
den Tags, wie in <link linkend="configure-kid3">Kid3 einrichten</link>
bei <guilabel>Benutzerbefehle</guilabel> beschrieben. Nach "Custom Source"
können auch eigene Quellen hinzugefügt werden. Dazu wird "Custom Source" durch
den Namen der Quelle ersetzt, dann Return gedrückt, die URL eingegeben und mit
<guibutton>Einstellungen speichern</guibutton> gesichert. Das resultierende
Browser-Kommando wird oben im Dialog dargestellt und nach Drücken des
<guibutton>Browser</guibutton>-Knopfes ausgeführt. Der Browser, welcher in den
Einstellungen konfiguriert werden kann, wird mit der gewählten Quelle
gestartet. Das gewünschte Cover-Bild kann dann aus dem Browser in das &kid3;
Fenster gezogen werden und wird im Bild-Feld von Tag 2 der selektierten
Dateien gesetzt.
</para>
<para>
Da nicht alle Browser Drag'n'Drop von Bildern unterstützen und häufig die
Bilder auf Websites mit einer URL unterlegt sind, erhält &kid3; in solchen
Fällen bloß die entsprechende URL und nicht das Bild. Wenn die URL auf ein
Bild zeigt, wird dieses heruntergeladen. Falls die URL jedoch auf sonst eine
Website hinweist, so muss von dieser auf das gewünschte Cover-Bild geschlossen
werden. Dies ist die Aufgabe der Tabelle <guilabel>URL
Ersetzung</guilabel>. Die linke Spalte <guilabel>Vergleich</guilabel> enthält
einen regulären Ausdruck, welcher mit der URL verglichen wird. Wenn eine
Übereinstimmung festgestellt wird, so werden die erhaltenen Klammer-Werte im
Muster der Spalte <guilabel>URL des Bildes</guilabel> ersetzt (\1 usw.). Der
ersetzte reguläre Ausdrucks enthält dann die URL des Bildes. Auf diese Weise
können auch Bilder von Amazon, Google Images, usw. per Drag'n'Drop importiert
werden. Natürlich können auch hier eigene Ersetzungen erfasst werden.
</para>
</listitem>
</varlistentry>

<varlistentry id="export">
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Exportieren...</guimenuitem>
</menuchoice></term>
<listitem><para>
Der <action>Export Dialog</action> wird verwendet, um die Daten aus den Tags in
einer Datei oder der Zwischenablage zu speichern. Das oberste Editierfeld
stellt einen einfachen Editor zur Verfügung, welcher eine Vorschau der zu
exportierenden Daten bietet. Falls die Export-Daten Tabulatorzeichen
enthalten, wird der Export in einer Tabelle dargestellt. Die
Daten werden aus den Tags der Dateien im aktuellen Verzeichnis generiert, und
zwar gemäß dem unten eingestellten Format.
</para>
<para>
Diese Formateinstellung ist gleich aufgebaut wie im Import Dialog: Im obersten
Feld ist der Titel (z.B. "CSV unquoted"), dann folgt der Header - dieser wird
nur am Anfang der Datei generiert. Nun folgt das Track-Format, es wird für
jeden Track angewendet. Schließlich gibt es noch einen Trailer, welcher die
Datei noch abschließt.
</para>
<para>
Die Formatfelder enthalten keine regulären Ausdrücke wie im Import Dialog,
sondern bloß Ausgabeformate, bei denen spezielle %-Ausdrücke durch Werte aus
den Tags ersetzt werden. Das ganze verhält sich also gleich wie beim
Dateinamenformat, es werden auch dieselben Codes verwendet, plus ein paar
zusätzliche. Nicht nur die unten aufgelisteten Codes sind möglich, es können
die Namen aller Tag Frames verwendet werden.
</para>

<itemizedlist>
<listitem><para>%s %{title} Titel (Song)</para></listitem>
<listitem><para>%a %{artist} Interpret (Artist)</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Kommentar (Comment)</para></listitem>
<listitem><para>%y %{year} Jahr (Year)</para></listitem>
<listitem><para>%t %{track} Nummer (Track)</para></listitem>
<listitem><para>%t %{track.n} Nummer mit Feldlänge n (z.B. 001 für %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Nummer (Track), ohne führende Null</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%f %{file} Dateiname (File name)</para></listitem>
<listitem><para>%p %{filepath} Pfadname</para></listitem>
<listitem><para>%u %{url} URL</para></listitem>
<listitem><para>%d %{duration} Dauer in Minuten:Sekunden</para></listitem>
<listitem><para>%D %{seconds} Dauer in Sekunden</para></listitem>
<listitem><para>%n %{tracks} Anzahl Tracks im Album</para></listitem>
<listitem><para>%e %{extension} Dateiendung</para></listitem>
<listitem><para>%O %{tag1} Das Format von Tag 1 (ID3v1.1 oder leer falls nicht
vorhanden)</para></listitem>
<listitem><para>%o %{tag2} Das Format von Tag 2 (ID3v2.3.0, ID3v2.4.0,
ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF oder leer falls nicht
vorhanden)</para></listitem>
<listitem><para>%b %{bitrate} Bitrate in kbit/s</para></listitem>
<listitem><para>%v %{vbr} VBR oder leer (nur für ID3v2.3 mit
id3lib)</para></listitem>
<listitem><para>%r %{samplerate} Samplerate in Hz</para></listitem>
<listitem><para>%m %{mode} Kanalmodus (Stereo oder Joint Stereo)</para></listitem>
<listitem><para>%h %{channels} Anzahl Kanäle (1 oder 2)</para></listitem>
<listitem><para>%k %{codec} Codec (z.B. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
MPC, APE, ASF, AIFF, WAV)</para></listitem>
</itemizedlist>

<para>
Mit diesen Formatcodes sind bereits einige Formate vordefiniert. "CSV
unquoted" trennt die einzelnen Felder durch Tabulatoren. Daten in diesem
Format können einfach wieder über das gleichnamige Importformat in &kid3;
importiert werden. "CSV quoted" setzt die Felder zusätzlich noch in
Anführungszeichen, was den Import in Tabellenkalkulationen erleichtert. Dafür
sollten in den Feldern keine Anführungszeichen vorkommen. "Extended M3U" und
"Extended PLS" erzeugen Stücklisten mit Zusatzinformationen und absoluten
Pfadnamen. "HTML" dient dazu, eine HTML-Seite mit verlinkten Tracks zu
erstellen. "Kover XML" generiert eine XML-Datei, welche vom
Cover-Druck-Programm Kover gelesen werden kann. "Technical Details" liefert
Informationen über Bitrate, Samplerate, Kanäle, usw. "Custom Format" schließlich
ist frei für ein eigenes Format. Natürlich können auch die anderen Formate
beliebig angepasst werden, oder es können noch mehr Formate in der Datei
<filename>kid3rc</filename> im Konfigurationsverzeichnis hinzugefügt werden.
</para>
<para>
Die Quelle der Daten (<guilabel>Tag 1</guilabel>
oder <guilabel>Tag 2</guilabel>) kann mit einem Auswahlfeld festgelegt
werden. Ein Klick auf <guibutton>In Datei</guibutton> bzw.
<guibutton>In Zwischenablage</guibutton> speichert die Daten in einer Datei
oder der Zwischenablage. <guibutton>OK</guibutton>
und <guibutton>Abbrechen</guibutton> beenden den Dialog,
wobei <guibutton>OK</guibutton> die aktuellen Einstellungen übernimmt.
</para></listitem>
</varlistentry>

<varlistentry id="create-playlist">
<term><menuchoice>
<guimenu>Datei</guimenu>
<guimenuitem>Stückliste erstellen...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Erzeugt eine Stückliste.</action> Das Format und der
Inhalt der Stückliste können mit verschiedenen Optionen bestimmt werden.
</para>
<para>
<guibutton>Wie Verzeichnisname</guibutton> generiert den Dateinamen der
Wiedergabeliste aus dem Namen des Verzeichnisses. Es kann aber auch ein
<guibutton>Format</guibutton> mit Werten aus den Tags benutzt werden,
z.B. "%{artist} - %{album}", um die Namen von Interpret und Album im
Dateinamen zu haben. Es können dieselben Format Codes wie bei
<link linkend="export">Exportieren</link> verwendet werden. Die
Dateierweiterung richtet sich nach dem Format der Stückliste.
</para>
<para>
Wo die Wiedergabeliste erstellt wird, kann bestimmt werden mit der
Auswahlliste <guilabel>Erstelle in</guilabel>
<variablelist>
<varlistentry><term>Aktuellem Verzeichnis</term>
<listitem><para>Die Stückliste wird im aktuellen Verzeichnis erstellt und
enthält nur Dateien aus diesem Verzeichnis.</para></listitem></varlistentry>
<varlistentry><term>Jedem Ordner</term>
<listitem><para>In jedem Verzeichnis, welches gelistete Dateien enthält, wird
eine eigene Stückliste erstellt, welche die Dateien aus dem jeweiligen
Verzeichnis enthält.
</para></listitem></varlistentry>
<varlistentry><term>Basisordner</term>
<listitem><para>Nur eine einzige Stückliste wird im Basisverzeichnis (d.h. dem
Verzeichnis der Dateiliste) erstellt, und sie enthält die gelisteten
Dateien aus dem Basisverzeichnis und allen Unterverzeichnissen.
</para></listitem></varlistentry>
</variablelist>
</para>
<para>
Das <guilabel>Format</guilabel> der Wiedergabeliste kann
<guilabel>M3U</guilabel>, <guilabel>PLS</guilabel> oder
<guilabel>XSPF</guilabel> sein.
</para>
<para>
<guibutton>Nur ausgewählte Dateien einfügen</guibutton> führt dazu, dass nur
ausgewählte Dateien in der Stückliste erscheinen. Wenn ein Verzeichnis
ausgewählt ist, so gelten all seine Dateien ebenfalls als selektiert.
Wenn diese Option nicht aktiviert ist, gelangen alle Audio-Dateien in die
Stückliste.
</para>
<para>
<guibutton>Sortiere nach Dateiname</guibutton> ordnet die Dateien wie üblich
nach dem Dateinamen in der Wiedergabeliste an. Mit <guibutton>Sortiere nach
Tag-Feld</guibutton> ist es möglich, eine Format-Zeichenkette mit Tag-Werten
für die Sortierung zu verwenden. "%{track.3}" kann beispielsweise benutzt
werden, um nach der Tracknummer zu sortieren (".3" wird verwendet, um 3
Stellen mit führenden Nullen zu kriegen, und somit korrekt nach der Nummer zu
sortieren). Es ist auch möglich, mehrere Codes zu verwenden,
z.B. "%{genre}%{year}", um nach einer Zeichenkette aus Genre und Jahr zu
sortieren.
</para>
<para>
Die Einträge in der Stückliste sind relative oder absolute Pfadangaben, je
nachdem ob <guibutton>Benutze relativen Pfad für Dateien in der Wiedergabeliste</guibutton> oder
<guibutton>Benutze vollen Pfad für Dateien in der Wiedergabeliste</guibutton>
gesetzt ist.
</para>
<para>
<guibutton>Nur Liste der Dateien schreiben</guibutton> führt dazu, dass die
Stückliste nur die Pfade zu den Dateien enthält. Wünscht man zusätzliche
Informationen, so steht <guibutton>Schreibe Informationen mit</guibutton>
einer Format-Zeichenfolge zur Verfügung, und es wird eine erweiterte
Stückliste generiert.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>Datei</guimenu>
<guimenuitem>Beenden</guimenuitem>
</menuchoice></term>
<listitem><para><action>Beendet die Anwendung.</action></para></listitem>
</varlistentry>

</variablelist>
</para>

</sect1>

<sect1 id="edit-menu">
<title>Das Menü Bearbeiten</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>A</keycap></keycombo>
</shortcut>
<guimenu>Bearbeiten</guimenu>
<guimenuitem>Alles auswählen</guimenuitem>
</menuchoice></term>
<listitem><para>Selektiert alle Dateien.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>A</keycap></keycombo>
</shortcut>
<guimenu>Bearbeiten</guimenu>
<guimenuitem>Abwählen</guimenuitem>
</menuchoice></term>
<listitem><para>Deselektiert alle Dateien.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Bearbeiten</guimenu>
<guimenuitem>Alles im Verzeichnis auswählen</guimenuitem>
</menuchoice></term>
<listitem><para>Selektiert alle Dateien im aktuellen
Verzeichnis.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>
</shortcut>
<guimenu>Bearbeiten</guimenu>
<guimenuitem>Vorangehende Datei</guimenuitem>
</menuchoice></term>
<listitem><para>Selektiert die vorangehende Datei.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
</shortcut>
<guimenu>Bearbeiten</guimenu>
<guimenuitem>Nächste Datei</guimenuitem>
</menuchoice></term>
<listitem><para>Selektiert die nächste Datei.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo>
</shortcut>
<guimenu>Bearbeiten</guimenu>
<guimenuitem>Suchen...</guimenuitem>
</menuchoice></term>
<listitem><para>Sucht Zeichenketten in den Dateinamen und Tags. Der
<guilabel>Suchen</guilabel> Dialog ist eine Teilmenge des <guilabel>Ersetzen</guilabel>-Dialogs, welcher unten beschrieben ist.
 </para></listitem>
</varlistentry>

<varlistentry id="find-replace">
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>R</keycap></keycombo>
</shortcut>
<guimenu>Bearbeiten</guimenu>
<guimenuitem>Ersetzen...</guimenuitem>
</menuchoice></term>
<listitem><para>Ein Dialog wird geöffnet, mit welchem sich Zeichenketten in
den Dateinamen und Tags suchen und ersetzen lassen. Die Suche kann auf
bestimmte Elemente eingeschränkt werden, indem bei <guilabel>Alles
selektieren</guilabel> das Häkchen entfernt wird und die gewünschten Elemente
ausgewählt werden. Es sind auch Optionen vorhanden, um rückwärts zu suchen,
Groß- und Kleinbuchstaben zu unterscheiden und für reguläre Ausdrücke.</para>
<para>Abhängig von der Anzahl Dateien kann die Suche etwas dauern, daher kann
sie durch Schließen des Dialogs abgebrochen werden.</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect1>

<sect1 id="tools-menu">
<title>Das Menü Extras</title>
<para>
<variablelist>

<varlistentry id="apply-filename-format">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>Dateinamenformat anwenden</guimenuitem>
</menuchoice></term>
<listitem><para>Wenn <guilabel>Während des Editierens formatieren</guilabel>
im Konfigurationsdialog beim Dateinamenformat deaktiviert ist, kann man mit diesem Menüpunkt
<action>die Formatierung auf die Namen der ausgewählten Dateien anwenden</action>.
Diese Funktion kann auch angewendet werden, um zu testen, ob die Dateinamen
dem eingestellten Format entsprechen. Hierzu sollten alle Dateien
gespeichert werden; nach Anwendung des Formates sind dann nur diejenigen
Dateien verändert (in der Dateiliste mit einem Diskettensymbol versehen), welche nicht
dem eingestellten Format entsprechen. Ungewollte Änderungen können
mit <guilabel>Zuletzt gespeicherte Fassung</guilabel>
rückgängig gemacht werden.
</para></listitem>
</varlistentry>

<varlistentry id="apply-tag-format">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>Tag-Format anwenden</guimenuitem>
</menuchoice></term>
<listitem><para>Wenn <guilabel>Während des Editierens formatieren</guilabel>
im Konfigurationsdialog beim Tag Format deaktiviert ist, kann man mit diesem Menüpunkt
<action>die Formatierung auf die Tags der ausgewählten Dateien anwenden</action>.
Diese Funktion kann auch angewendet werden, um zu testen, ob die Tags dem
eingestellten Format entsprechen. Hierzu sollten alle Dateien
gespeichert werden; nach Anwendung des Formates sind dann nur diejenigen
Dateien verändert (in der Dateiliste mit einem Diskettensymbol versehen), welche nicht
dem eingestellten Format entsprechen. Ungewollte Änderungen können
mit <guilabel>Zuletzt gespeicherte Fassung</guilabel>
rückgängig gemacht werden.
</para></listitem>
</varlistentry>

<varlistentry id="apply-text-encoding">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>Textkodierung anwenden</guimenuitem>
</menuchoice></term>
<listitem><para>Setzt die <guilabel>Textkodierung</guilabel>, welche
in <guilabel>Einstellungen/Kid3 einrichten.../Tags/Tag 2</guilabel>
eingestellt ist, für alle ausgewählten Dateien. Wenn UTF8 eingestellt ist,
so wird für ID3v2.3.0 Tags UTF16 verwendet, denn dieses Format unterstützt
UTF8 nicht.</para></listitem>
</varlistentry>

<varlistentry id="rename-directory">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>Verzeichnis umbenennen...</guimenuitem>
</menuchoice></term>
<listitem><para>Dieser Dialog bietet die Möglichkeit, automatisch das aktuelle
Verzeichnis gemäß den Tags umzubenennen. Verschiedene Formate sind
vordefiniert und Informationen über Interpret, Album und Jahr in den
Verzeichnisnamen zu übernehmen. Es ist auch möglich, ein eigenes Format zu
definieren, die folgenden Codes können verwendet werden, um
Werte aus den Tags im Verzeichnisnamen einzusetzen:
</para>

<itemizedlist>
<listitem><para>%s %{title} Titel (Song)</para></listitem>
<listitem><para>%a %{artist} Interpret (Artist)</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Kommentar (Comment)</para></listitem>
<listitem><para>%y %{year} Jahr (Year)</para></listitem>
<listitem><para>%t %{track} Nummer (Track))</para></listitem>
<listitem><para>%t %{track.n} Nummer mit Feldlänge n (z.B. 001 für %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Nummer (Track), ohne führende Null</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
</itemizedlist>

<para>
Wenn ein Verzeichnis-Trennzeichen "/" im Format gefunden wird, werden mehrere
Verzeichnisse erstellt. Will man ein neues Verzeichnis erstellen statt das
aktuelle Verzeichnis umbenennen, so wählt man <guilabel>Verzeichnis
erstellen</guilabel> statt <guilabel>Verzeichnis umbenennen</guilabel>. Die
Quelle der Tag-Information kann zwischen
<guilabel>Von Tag 1 und Tag 2</guilabel>, <guilabel>Von Tag 1</guilabel> und
<guilabel>Von Tag 2</guilabel> ausgewählt werden. Die voraussichtliche
Verzeichnisnamensänderung für die erste Datei kann in den Abschnitten
<guilabel>Von</guilabel> und <guilabel>Nach</guilabel> des Dialogs gesehen
werden.
</para>
<para>
Es können auch mehrere Verzeichnisse umbenannt werden, indem sie selektiert
werden.
</para></listitem>
</varlistentry>

<varlistentry id="number-tracks">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>Tracks nummerieren...</guimenuitem>
</menuchoice></term>
<listitem><para>
Falls die Track-Nummern in den Tags nicht vorhanden oder falsch sind, so
lassen sich mit dieser Funktion <action>die Tracks automatisch aufsteigend
nummerieren</action>. Im Dialog kann die <guilabel>Startnummer</guilabel>
angegeben werden. Falls nur ein Teil der Tracks nummeriert werden soll, so
sind diese im Voraus auszuwählen.
</para><para>
Wenn <guilabel>Anzahl Stücke</guilabel> markiert ist, wird auch
die Anzahl Tracks in den Tags gesetzt.
</para><para>
Es können auch die Tracks über mehrere Ordner hinweg nummeriert werden. Dazu
müssen die Verzeichnisse aufgeklappt und selektiert werden.
</para><para>
Wenn <guilabel>Zähler für jedes Verzeichnis zurücksetzen</guilabel> aktiviert
ist, wird die Nummerierung bei jedem Verzeichnis mit der
<guilabel>Startnummer</guilabel> begonnen falls mehrere Verzeichnisse
ausgewählt sind.
</para><para>
Der Dialog kann auch dazu benutzt werden, bestehende Track-Nummern neu zu
formatieren, ohne ihren Wert zu verändern. Dazu muss das Häkchen bei der
<guilabel>Startnummer</guilabel> entfernt werden. Wenn <guilabel>Anzahl
Stücke</guilabel> markiert ist, so wird das Total hinzugefügt. Falls es nicht
erwünscht ist, die Anzahl Stücke in allen ausgewählten Dateien zu setzen, muss
auch diese Option deaktiviert werden.
</para><para>
</para></listitem>
</varlistentry>

<varlistentry id="filter">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>Filter...</guimenuitem>
</menuchoice></term>
<listitem>
<para>
Der Filter kann dazu verwendet werden, nur diejenigen Dateien anzeigen, welche
gewisse Eigenschaften erfüllen. Dies kann dann nützlich sein, wenn man die
Tags oder Dateinamen in einer größeren Sammlung bereinigen möchte, jedoch nur
diejenigen Dateien bearbeiten möchte, welche nicht dem gewünschten Schema
entsprechen. Der Ausdruck, der bestimmt, welche Dateien angezeigt werden,
benutzt dieselben Formatcodes, welche auch beim Dateinamenformat, Importieren
und Exportieren verwendet werden.
</para>

<itemizedlist>
<listitem><para>%s %{title} Titel (Song)</para></listitem>
<listitem><para>%a %{artist} Interpret (Artist)</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Kommentar (Comment)</para></listitem>
<listitem><para>%y %{year} Jahr (Year)</para></listitem>
<listitem><para>%t %{track} Nummer (Track))</para></listitem>
<listitem><para>%t %{track.n} Nummer mit Feldlänge n (z.B. 001 für %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Nummer (Track), ohne führende Null</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>

<listitem><para>%f %{file} Dateiname (File name)</para></listitem>
<listitem><para>%p %{filepath} Absoluter Pfadname</para></listitem>
<listitem><para>%e %{extension} Dateiendung</para></listitem>
<listitem><para>%O %{tag1} Das Format von Tag 1 (ID3v1.1 oder leer falls nicht
vorhanden)</para></listitem>
<listitem><para>%o %{tag2} Das Format von Tag 2 (ID3v2.3.0, ID3v2.4.0,
ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF oder leer falls nicht
vorhanden)</para></listitem>
<listitem><para>%b %{bitrate} Bitrate in kbit/s</para></listitem>
<listitem><para>%v %{vbr} VBR oder leer (nur für ID3v2.3 mit
id3lib)</para></listitem>
<listitem><para>%r %{samplerate} Samplerate in Hz</para></listitem>
<listitem><para>%m %{mode} Kanalmodus (Stereo oder Joint Stereo)</para></listitem>
<listitem><para>%h %{channels} Anzahl Kanäle (1 oder 2)</para></listitem>
<listitem><para>%k %{codec} Codec (z.B. MPEG 1 Layer 3, MP4, Ogg Vorbis, FLAC,
MPC, APE, ASF, AIFF, WAV)</para></listitem>
<listitem><para>%1a %1{artist}, ... Der Präfix 1 wird benutzt, um Werte von Tag 1 zu
erhalten</para></listitem>
<listitem><para>%2a %2{artist}, ... Der Präfix 2 wird benutzt, um Werte von Tag 2 zu
erhalten</para></listitem>
</itemizedlist>

<para>
Diese Codes werden mit dem Wert für die Datei ersetzt
und die resultierenden Zeichenketten können mit folgenden Operatoren
verglichen werden:
</para>
<itemizedlist>
<listitem><para>s1 equals s2: wahr wenn s1 und s2 gleich sind.</para></listitem>
<listitem><para>s1 contains s2: wahr wenn s2 in s1 enthalten ist.</para></listitem>
<listitem><para>s matches re: wahr wenn s den regulären Ausdruck re erfüllt.</para></listitem>
</itemizedlist>
<para>
Wahre Ausdrücke werden durch 1 ersetzt, falsche durch 0. Wahre Werte
repräsentieren nebst 1 auch true, on und yes, falsche Werte entsprechend 0,
false, off und no. Diese Wahrheitwerte können durch die logischen Operatoren
not, and und or verknüpft werden (die Priorität ist in dieser Reihenfolge),
und mit Klammern gruppiert werden.
</para>
<para>
Einige Filterregeln sind bereits vordefiniert und können als Beispiele für
eigene Ausdrücke dienen:
</para>

<variablelist>
<varlistentry><term>All</term><listitem>
<para>
Wenn die Dateiliste gefiltert ist - dies wird mit "[Gefiltert]" in der
Titelzeile angezeigt - und man möchte wieder alle Dateien anzeigen, kann das
Filtern mit diesem Filter rückgängig gemacht werden. Es wird ein leerer
Ausdruck verwendet, ein Wahrheitswert wie true hätte aber denselben Effekt.
</para>
</listitem></varlistentry>

<varlistentry><term>Filename Tag Mismatch</term><listitem>
<para><userinput>
not (%{filepath} contains "%{artist} - %{album}/%{track} %{title}")
</userinput></para>
<para>
Testet, ob ein Dateipfad dem Dateinamenformat entspricht. Diese Regel wird
automatisch angepasst, wenn sich das Dateinamenformat ändert.
</para>
</listitem></varlistentry>

<varlistentry><term>No Tag 1</term><listitem>
<para><userinput>
%{tag1} equals ""
</userinput></para>
<para>Es werden nur Dateien ohne Tag 1 angezeigt.</para>
</listitem></varlistentry>

<varlistentry><term>No Tag 2</term><listitem>
<para><userinput>
%{tag2} equals ""
</userinput></para>
<para>Es werden nur Dateien ohne Tag 2 angezeigt.</para>
</listitem></varlistentry>

<varlistentry><term>ID3v2.3.0 Tag</term><listitem>
<para><userinput>
%{tag2} equals "ID3v2.3.0"
</userinput></para>
<para>Es werden nur Dateien mit ID3v2.3.0 Tag angezeigt.</para>
</listitem></varlistentry>

<varlistentry><term>ID3v2.4.0 Tag</term><listitem>
<para><userinput>
%{tag2} equals "ID3v2.4.0"
</userinput></para>
<para>Es werden nur Dateien mit ID3v2.4.0 Tag angezeigt.</para>
</listitem></varlistentry>

<varlistentry><term>Tag 1 != Tag 2</term><listitem>
<para><userinput>
not (%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist}
equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals
%2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre})
</userinput></para>
<para>Es werden Dateien mit Unterschieden zwischen Tag 1 und Tag 2
angezeigt.</para>
</listitem></varlistentry>

<varlistentry><term>Tag 1 == Tag 2</term><listitem>
<para><userinput>
%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist}
equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals
%2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre}
</userinput></para>
<para>Es werden Dateien mit identischen Tag 1 und Tag 2 angezeigt.</para>
</listitem></varlistentry>

<varlistentry><term>Incomplete</term><listitem>
<para><userinput>
%{title} equals "" or %{artist} equals "" or %{album} equals "" or %{year} equals "" or %{tracknumber} equals "" or %{genre} equals ""
</userinput></para>
<para>Es werden nur Dateien angezeigt, welche leere Standard-Tag-Werte
haben (Titel, Interpret, Album, Datum, Tracknummer, Genre).</para>
</listitem></varlistentry>

<varlistentry><term>No Picture</term><listitem>
<para><userinput>
%{picture} equals ""
</userinput></para>
<para>Es werden nur Dateien ohne Bild angezeigt.</para>
</listitem></varlistentry>

<varlistentry><term>Custom Filter</term><listitem>
<para>
Dieser Eintrag kann verwendet werden, um einen eigenen Filter hinzuzufügen. Um
beispielsweise nur Dateien anzuzeigen, deren Interpret mit "The" beginnt,
ersetzt man "Custom Filter" durch einen Namen wie "The Bands" und drückt die
Enter Taste. Dann fügt man folgenden Ausdruck in das Eingabefeld ein:
</para>
<para><userinput>
%{artist} matches "The.*"
</userinput></para>
<para>
Gespeichert wird mit <guibutton>Einstellungen speichern</guibutton>.
Die Dateien werden mit <guibutton>Anwenden</guibutton> gefiltert. Alle
bearbeiteten Dateien werden im Textfeld angezeigt, mit einem "+" vor solchen,
die den Filterausdruck erfüllen, und einem "-" vor den anderen. Wenn das
Filtern fertig ist, werden nur noch diejenigen Dateien angezeigt, deren
Interpret mit "The" beginnt, und in der Titelzeile wird "[Gefiltert]" angezeigt.
</para>
</listitem></varlistentry>

</variablelist>

</listitem>
</varlistentry>

<varlistentry id="convert-to-id3v24">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>ID3v2.3 nach ID3v2.4 konvertieren</guimenuitem>
</menuchoice></term>
<listitem><para>
Wenn in den ausgewählten Dateien ID3v2.3 Tags vorhanden sind, so werden
sie <action>zu ID3v2.4 Tags konvertiert</action>. Frames, welche von TagLib
nicht unterstützt sind, werden verworfen. Nur Dateien ohne ungesicherte
Änderungen werden konvertiert.
</para></listitem>
</varlistentry>

<varlistentry id="convert-to-id3v23">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>ID3v2.4 nach ID3v2.3 konvertieren</guimenuitem>
</menuchoice></term>
<listitem><para>
Wenn in den ausgewählten Dateien ID3v2.4 Tags vorhanden sind, so werden
sie <action>zu ID3v2.3 Tags konvertiert</action>. Nur Dateien ohne
ungesicherte Änderungen werden konvertiert.
</para></listitem>
</varlistentry>

<varlistentry id="play">
<term><menuchoice>
<guimenu>Extras</guimenu>
<guimenuitem>Wiedergabe</guimenuitem>
</menuchoice></term>
<listitem><para>
Damit öffnet sich eine einfache Werkzeugleiste zum Abspielen von Audio-Dateien.
Sie enthält Knöpfe für die grundlegenden Operationen
(<guibutton>Wiedergabe/Pause</guibutton>,
<guibutton>Wiedergabe stoppen</guibutton>, <guibutton>Zurück</guibutton>,
<guibutton>Vorwärts</guibutton>, <guibutton>Schließen</guibutton>),
Regler für Position und Lautstärke und eine Anzeige der aktuellen Position.
Abgespielt werden die selektierten Stücke bei Mehrfachselektion bzw. alle
Stücke wenn eine oder keine Datei selektiert ist.
</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect1>

<sect1 id="settings-menu">
<title>Das Menü Einstellungen</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Einstellungen</guimenu>
<guimenuitem>Werkzeugleiste anzeigen</guimenuitem>
</menuchoice></term>
<listitem><para><action>Schaltet die Anzeige der Werkzeugleiste ein und aus.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Einstellungen</guimenu>
<guimenuitem>Statusleiste anzeigen</guimenuitem>
</menuchoice></term>
<listitem><para><action>Schaltet die Anzeige der Statusleiste, welche
längere Aktionen wie Öffnen und Speichern eines Verzeichnisses anzeigt, ein
und aus.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Einstellungen</guimenu>
<guimenuitem>Bild anzeigen</guimenuitem>
</menuchoice></term>
<listitem><para><action>Schaltet die Anzeige des Cover-Bildes ein und aus.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Einstellungen</guimenu>
<guimenuitem>Tags automatisch ausblenden</guimenuitem>
</menuchoice></term>
<listitem><para>
Wenn diese Option aktiv ist, werden leere Tags automatisch ausgeblendet.
Manuell lassen sich die <guilabel>Datei</guilabel>, <guilabel>Tag 1</guilabel>
und <guilabel>Tag 2</guilabel> Sektionen durch Druck auf die entsprechenden
<guibutton>-</guibutton> bzw. <guibutton>+</guibutton> Schaltflächen zu- und
aufklappen.
</para></listitem>
</varlistentry>

<varlistentry id="configure-kid3">
<term><menuchoice>
<guimenu>Einstellungen</guimenu>
<guimenuitem>Kid3 einrichten...</guimenuitem>
</menuchoice></term>
<listitem><para>Öffnet den <action>Konfigurationsdialog</action>,
der aus verschiedenen Seiten besteht, mit Optionen für Tags, Dateien, Benutzerbefehle und Netzwerk.
</para>
<para>
Optionen für Tags sind auf der Seite <guilabel>Tags</guilabel> zu finden,
welche ihrerseits in drei Reiter unterteilt ist für
<guilabel>Tag 1</guilabel>, <guilabel>Tag 2</guilabel> und
<guilabel>Tag 1 und Tag 2</guilabel>.
</para>
<para>
Wenn <guilabel>Markiere abgeschnittene Felder</guilabel> aktiv ist, werden
abgeschnittene ID3v1.1 Felder rot markiert. Die Textfelder in ID3v1.1 Tags
haben bloß 30 Zeichen, der Kommentar nur 28 Zeichen. Auch Genre und Nummer
sind Beschränkungen unterworfen, so dass Felder gekürzt werden
können, wenn sie importiert oder von ID3v2 konvertiert werden.
Abgeschnittene Felder und ihre Datei werden rot markiert; die Markierung
wird entfernt, nachdem das Feld editiert worden ist.
</para>
<para>
Mit <guilabel>Text Codierung</guilabel> für <guilabel>ID3v1</guilabel> kann
die Codierung, welche für ID3v1 Tags verwendet wird, eingestellt werden.
Standardmäßig wird hier ISO-8859-1 erwartet, daher wird empfohlen, diese
Einstellung so zu lassen. Da jedoch Tags mit anderer Codierung anzutreffen
sind, kann hier eine andere Codierung gewählt werden, so dass dann die ID3v1
Tags nach ID3v2 transferiert werden können, welches Unicode Zeichen unterstützt.
</para>
<para>
Das Markierungsfeld
<guilabel>Benutze Format Nummer/Anzahl Stücke</guilabel> bewirkt, dass im
Tracknummer-Feld bei den ID3v2 Tags nicht bloß die Tracknummer gespeichert
wird, sondern auch die Gesamtzahl der Stücke im Verzeichnis.
</para>
<para>
Wenn <guilabel>Genre als Text statt als Nummer</guilabel> aktiviert ist, werden
alle Genres als Text gespeichert, auch wenn ein ID3v1-Code für das Genre
existiert. Ohne diese Einstellungen werden solche Genres als die Nummer des
entsprechenden ID3v1-Codes gespeichert (in Klammern für ID3v2.3). Das Genre
Metal wird also abhängig von dieser Option entweder als "Metal" oder als "(9)"
gespeichert. Genres, für welche kein ID3v1-Code existiert, werden immer als
Text gespeichert. Der Sinn dieser Option ist es, die Kompatibilität mit
Geräten zu verbessern, welche die Codes nicht korrekt interpretieren.
</para>
<para>
<guilabel>Text Codierung</guilabel> bestimmt die Codierung von ID3v2
Elementen und kann
auf <guilabel>ISO-8859-1</guilabel>, <guilabel>UTF16</guilabel> oder
<guilabel>UTF8</guilabel> gesetzt werden. <guilabel>UTF8</guilabel> ist für
ID3v2.3.0 nicht gültig; wenn dieser Wert gesetzt ist, wird
stattdessen <guilabel>UTF16</guilabel> verwendet.
Für ID3v2.4.0 sind alle drei Codierungen möglich.
</para>
<para>
<guilabel>Version für neue Tags</guilabel> legt fest, ob neue ID3v2 Tags mit
der Version 2.3.0 oder 2.4.0 erzeugt werden. Im ersteren Fall wird id3lib
verwendet, TagLib kommt nur dann zum Einsatz, wenn ein ID3v2.4.0 Tag
bearbeitet werden muss. Mit der Einstellung <guilabel>ID3v2.4.0
(TagLib)</guilabel> wird für MP3-Dateien immer die TagLib verwendet;
veränderte oder neu erstellte Tags werden dann als ID3v2.4.0 gespeichert.
Mit <guilabel>ID3v2.3.0 (TagLib)</guilabel> wird TagLib auch für ID3v2.3.0
Tags verwendet.
</para>
<para>
<guilabel>Anzahl der Stellen in Tracknummer</guilabel> bestimmt die Zahl der
Dezimalstellen in den Tracknummer-Feldern. Die Nummern werden mit führenden
Nullen auf die eingestellte Anzahl Stellen erweitert. Beispielsweise wird mit
dem Wert 2 die Tracknummer 5 als "05" gesetzt.
</para>
<para>
Das Auswahlfeld
<guilabel>Name des Kommentar-Feldes</guilabel> ist für Ogg/Vorbis und
FLAC-Dateien relevant und bestimmt den Namen des Feldes, welches für
Kommentare verwendet wird. Hier scheinen verschiedene Anwendungen
unterschiedliche Namen zu verwenden, "COMMENT" wird beispielsweise von xmms
benutzt, während amaroK "DESCRIPTION" verwendet.
</para>
<para>
Das Format von Bildern in Ogg/Vorbis-Dateien wird bestimmt durch
<guilabel>Name des Bild-Feldes</guilabel> und kann
<guilabel>METADATA_BLOCK_PICTURE</guilabel> oder <guilabel>COVERART</guilabel>
sein. Das erstere ist der offizielle Standard und benutzt dasselbe Format wie
Bilder in FLAC-Dateien. Bei COVERART handelt es sich um eine frühere,
inoffizielle Methode, um Bilder in Vorbis-Tags zu codieren. Manche Player
benutzen dieses Feld.
</para>
<para>
Wenn das Häkchen bei <guilabel>Markieren wenn größer als</guilabel> gesetzt
ist, so werden Dateien mit Bildern, welche die angegebene Größe überschreiten,
rot markiert. Damit können Dateien mit übergroßen Bildern, welche von
gewissen Applikationen und Playern nicht akzeptiert werden, aufgespürt
werden. Der vorgegebene Limit ist 131072 Bytes (128 KB).
</para>
<para>
<guilabel>Eigene Genres</guilabel> kann zur Definition von Genres benutzt werden,
welche nicht in der Standard-Liste enthalten sind, so z.B. "Gothic Metal".
Solche Genres sind dann im <guilabel>Genre</guilabel> Auswahlfeld von
<guilabel>Tag 2</guilabel> verfügbar. Für ID3v1.1 Tags können nur
die vordefinierten Genres verwendet werden.
</para>
<para>
Die Liste mit den eigenen Genres kann auch dazu verwendet werden, die Anzahl
der im <guilabel>Genre</guilabel> Auswahlfeld angebotenen Einträge auf
diejenigen zu reduzieren, welche man braucht. Falls die Musiksammlung
hauptsächlich aus Metal, Gothic Metal, Ancient und Hard Rock Nummern
besteht, so kann man diese Genres eingeben und
<guilabel>Nur eigene Genres anzeigen</guilabel> markieren. Das
<guilabel>Tag 2</guilabel> <guilabel>Genre</guilabel> Auswahlfeld enthält
dann nur noch diese vier Genres, und man braucht nicht mehr die ganze lange
Liste nach ihnen zu durchsuchen. Bei dieser Beispielkonfiguration sind im
<guilabel>Tag 1</guilabel> <guilabel>Genre</guilabel> Auswahlfeld nur noch
Metal und Hard Rock verfügbar, denn diese zwei Einträge sind
Standard Genres. Wenn <guilabel>Nur eigene Genres anzeigen</guilabel> nicht
markiert ist, so werden die eigenen Genres am Ende der Auswahlliste
aufgeführt.
</para>
<para>
<guilabel>Schnellzugriff-Elemente</guilabel> bestimmt, welche Frametypen immer
bei <link linkend="tag2">Tag 2</link> angezeigt werden. Solche Frames können
dann hinzugefügt werden, ohne zuerst den <guibutton>Hinzufügen</guibutton>
Knopf zu drücken. Die Reihenfolge dieser Schnellzugriff-Elemente kann durch
Ziehen und Loslassen der Elemente verändert werden.
</para>
<para>
<guilabel>Tag Format</guilabel> enthält Einstellungen für das Format
der Tags.
Wenn <guilabel>Während dem Editieren formatieren</guilabel> aktiviert ist,
wird die Eingabe während dem Editieren automatisch formatiert.
<guilabel>Groß/Kleinschreibung</guilabel> kann auf <guilabel>Keine
Änderungen</guilabel>, <guilabel>Alles Kleinbuchstaben</guilabel>,
<guilabel>Alles Großbuchstaben</guilabel>, <guilabel>Den ersten Buchstaben
groß</guilabel> oder <guilabel>Alle ersten Buchstaben groß</guilabel>
gesetzt werden. Um die Eigenheiten einer Sprache bei der Konversion zwischen
Klein- und Großbuchstaben zu berücksichtigen, kann eine Sprache in der
darunterliegenden Auswahlliste gewählt werden.
Die <guilabel>Zeichen ersetzen</guilabel> Liste kann mit beliebigen Zuordnungen
von Zeichenketten gefüllt werden. Eine neue Zuordnung kann
hinzugefügt werden, indem in der <guilabel>Von</guilabel> Zelle einer
Zeile der zu ersetzende Text eingegeben wird und dann in der
<guilabel>Nach</guilabel> Spalte der Ersetzungstext. Zum Löschen einer
Zuordnung wird die <guilabel>Von</guilabel> Zelle auf einen leeren Wert
gesetzt (z.B. indem man zuerst einen Leerschlag eingibt und diesen dann wieder
löscht). Einfügen und Löschen von Zeilen ist auch über das
Kontext-Menü möglich, welches erscheint, wenn man die rechte
Maustaste drückt. Ersetzungen werden nur durchgeführt, wenn das
<guilabel>Zeichen ersetzen</guilabel> Markierungsfeld aktiviert ist.
</para>
<para>
Auf der Seite <guilabel>Dateien</guilabel> bestimmt das Markierungsfeld
<guilabel>Zuletzt geöffnete Dateien laden</guilabel>, ob &kid3; beim nächsten
Start wieder die zuletzt gewählte Datei öffnet und selektiert. Mit
<guilabel>Datei-Zeitstempel nicht verändern</guilabel> kann eingestellt
werden, dass die Modifikationszeit der Datei nicht verändert wird.
</para>
<para>
Wenn <guilabel>Änderungen markieren</guilabel> aktiviert ist, werden veränderte
Felder markiert, indem der Hintergrund des Namens grau gesetzt wird.
<guilabel>Dateiname für Cover</guilabel> setzt den Namen, welcher
vorgeschlagen wird, wenn ein eingebettetes Bild als Datei exportiert wird.
</para>
<para>
<guilabel>Dateinamen Format</guilabel> enthält Einstellungen für das
Format der Dateinamen. Dabei sind die selben Optionen wie bei
<guilabel>Tag Format</guilabel> möglich.
</para>
<para>
Die Seite <guilabel>Benutzerbefehle</guilabel> enthält eine Tabelle mit
Befehlen, welche über das Kontext Menü der Dateiliste ausgewählt
werden können. Bei
kritischen Operationen, beispielsweise dem Löschen von Dateien, empfiehlt es
sich, <guilabel>Nachfragen</guilabel> zu markieren, damit vor dem Ausführen
des Befehls eine Bestätigung verlangt wird.
<guilabel>Ausgabe</guilabel> kann markiert werden, um die Ausgabe von
Konsolen-Applikationen zu sehen (Standard und
Fehler-Ausgabe). <guilabel>Name</guilabel> ist der Text, welcher im Kontext
Menü dargestellt wird. <guilabel>Befehl</guilabel> schließlich ist
die auszuführende Kommandozeile. Argumente können mit den
folgenden Codes übergeben werden:
</para>

<itemizedlist>
<listitem><para>%F %{files} Dateipfad (eine Liste wenn mehrere Dateien selektiert sind)</para></listitem>
<listitem><para>%f %{file} Pfad einer einzelnen Datei</para></listitem>
<listitem><para>%uF %{urls} URLs (eine Liste wenn mehrere Dateien selektiert sind)</para></listitem>
<listitem><para>%uf %{url} URL zu einer einzelnen Datei</para></listitem>
<listitem><para>%d %{directory} Verzeichnis</para></listitem>
<listitem><para>%s %{title} Titel (Song)</para></listitem>
<listitem><para>%a %{artist} Interpret (Artist)</para></listitem>
<listitem><para>%l %{album} Album</para></listitem>
<listitem><para>%c %{comment} Kommentar (Comment)</para></listitem>
<listitem><para>%y %{year} Jahr (Year)</para></listitem>
<listitem><para>%t %{track} Nummer (Track)</para></listitem>
<listitem><para>%t %{track.n} Nummer mit Feldlänge n (z.B. 001 für %{track.3})</para></listitem>
<listitem><para>%T %{tracknumber} Nummer (Track), ohne führende Null</para></listitem>
<listitem><para>%g %{genre} Genre</para></listitem>
<listitem><para>%b %{browser} Kommando zum Starten des Web Browsers</para></listitem>
<listitem><para>%q %{qmlpath} Basisverzeichnis der mitgelieferten QML-Dateien</para></listitem>
</itemizedlist>

<para>
Der Code <command>@separator</command> kann verwendet werden, um eine
Trennlinie in das Benutzerbefehle-Kontextmenü einzufügen. Menüpunkte können in
Untermenüs gruppiert werden, indem man sie mit <command>@beginmenu</command>
und <command>@endmenu</command> Befehlen umgibt. Der Name des Untermenüs wird
durch die Spalte <guilabel>Name</guilabel> des <command>@beginmenu</command>
Befehls definiert.
</para>

<para id="configure-user-actions-qml">
Zum Ausführen von QML Skripten wird als Befehl <command>@qml</command>
verwendet. Danach wird der Pfad zum QML-Skript angegeben. Die mitgelieferten
Skripte liegen im Verzeichnis <filename>%{qmlpath}/script/</filename> (unter
Linux typischerweise <filename>/usr/share/kid3/qml/script/</filename>, bei
Windows in <filename>qml/script/</filename> innerhalb des
Installationsverzeichnisses, und bei OS X im App-Verzeichnis
<filename>kid3.app/Contents/Resources/qml/script/</filename>). Eigene Skripte
können aber auch in einem beliebigen anderen Verzeichnis gespeichert werden.
Wenn der QML-Code grafische Elemente innerhalb eines Fensters öffnet, so muss
<command>@qmlview</command> anstelle von <command>@qml</command> verwendet
werden. Weitere Parameter werden dem QML-Skript übergeben und sind dort über
die Funktion <function>getArguments()</function> verfügbar. Eine Übersicht
einiger in QML verfügbarer Funktionen und Eigenschaften findet sich im Anhang
<link linkend="qml-interface">QML Schnittstelle</link>.
</para>

<para>
Das Kommando, welches mit %{browser} eingefügt werden kann, wird oberhalb der
Tabelle im Eingabefeld <guilabel>Web Browser</guilabel> definiert. Damit
lassen sich leicht Webseiten mit Informationen zu den Audiodateien aufrufen.
Zum Beispiel startet
<screen width="40">
<userinput>%{browser} http://lyricwiki.org/%u{artist}:%u{title}</userinput>
</screen>
eine Anfrage in <ulink url="http://www.lyricwiki.org">LyricWiki</ulink> mit
Interpret und Titel. Das "u" in %u{artist} und %u{title} bewirkt, dass Interpret %{artist} und Titel
%{title} URL-codiert werden. In gleicher Weise lassen sich auch leicht andere Abfragen
definieren, z.B. eine Bildsuche bei
<ulink url="http://www.google.com">Google</ulink>:
<screen width="40">
<userinput>%{browser} http://images.google.com/images?q=%u{artist}%20%u{album}</userinput>
</screen>
</para>
<para>
Um dem Tag 2 Album Cover Bilder hinzuzufügen, kann man mit den oben
beschriebenen Benutzerbefehlen über Google Images oder Amazon nach Bildern
suchen. Die Bilder können mit "Drag and Drop" hinzugefügt werden. Bilder können auch
mit <guibutton>Hinzufügen</guibutton> eines Bild Elementes und Importieren
einer Datei oder Einfügen aus der Zwischenablage in ein Tag gebracht
werden. Unterstützt sind Bilder für ID3v2, MP4, FLAC, Ogg und ASF Tags.
</para>
<para>
Zum Löschen und Hinzufügen von
Einträgen steht in der Tabelle ein Kontext Menü zur Verfügung.
</para>
<para>
Die <guilabel>Netzwerk</guilabel> Seite enthält bloß ein Textfeld für die
Adresse des Netzwerk Proxys und optional der Portnummer, abgetrennt durch
einen Doppelpunkt. Dieser Proxy wird für den Import von einem Internet Server
verwendet, wenn das Kästchen davor markiert ist.
</para>

<para>
Die verfügbaren Plugins können in der Seite <guilabel>Erweiterungen</guilabel>
ein- bzw. ausgeschaltet werden. Die Plugins sind in zwei Listen unterteilt.
<guilabel>Metadaten Plugins &amp; Priorität</guilabel> enthält Plugins, welche
Audio-Datei-Formate unterstützen. Die Reihenfolge der Einträge ist
entscheidend, denn sie werden der Reihe nach durchprobiert. Gewisse Formate
werden von mehreren Plugins unterstützt, daher werden Dateien durch das erste
Plugin, welches sie unterstützt, geöffnet. <guilabel>TaglibMetadata</guilabel>
unterstützt die meisten Formate; wenn es zuoberst in der Liste ist, wird es
die meisten Dateien öffnen. Um ein anderes Plugin zu verwenden, muss es vor
<guilabel>TaglibMetadata</guilabel> in der Liste stehen. Details über die
Metadaten Plugins und Gründe, warum man sie statt TagLib verwenden möchte,
folgen.

<itemizedlist>
<listitem><para><guilabel>Id3libMetadata</guilabel>:
Benutzt <ulink url="http://id3lib.sourceforge.net">id3lib</ulink> für ID3v1.1
und ID3v2.3 Tags in MP3, MP2 und AAC Dateien; unterstützt einige Frame-Typen
mehr als TagLib. Ein weiterer Grund für die Verwendung ist, dass TagLib
ID3v2.3 erst seit Version 1.8 unterstützt.</para></listitem>
<listitem><para><guilabel>OggFlacMetadata</guilabel>:
Benutzt <ulink url="http://xiph.org/ogg/">libogg</ulink>,
<ulink url="http://xiph.org/vorbis/">libvorbis und libvorbisfile</ulink> für Ogg
Dateien und zusätzlich <ulink url="http://flac.sourceforge.net">libFLAC++
und libFLAC</ulink> für FLAC Dateien. Gründe für die Benutzung sind Bilder in
Ogg Dateien - solche werden von TagLib nicht unterstützt - und dass es die
offiziellen Bibliotheken dieser Formate sind.</para></listitem>
<listitem><para><guilabel>TaglibMetadata</guilabel>:
Benutzt <ulink url="http://taglib.github.io/">TagLib</ulink>, welche viele
Datei-Formate unterstützt, seit Version 1.8 auch ID3v2.3, so dass sie für
alle Audio-Dateien verwendet werden kann, welche &kid3; unterstützt.
</para></listitem>
<listitem><para><guilabel>Mp4v2Metadata</guilabel>:
<ulink url="http://code.google.com/p/mp4v2">mp4v2</ulink> wurde ursprünglich
von &kid3; für M4A-Dateien verwendet. Mittlerweile ist die Unterstützung von
TagLib für dieses Format so gut, dass dieses Plugin nur erstellt wird, wenn
dies explizit gefordert wird.
</para></listitem>
</itemizedlist>

<guilabel>Verfügbare Erweiterungen</guilabel> listet die verbleibenden Plugins
auf. Ihre Reihenfolge ist unwichtig, sie können über die Kästchen links
ein- oder ausgeschaltet werden.

<itemizedlist>
<listitem><para><guilabel>AmazonImport</guilabel>:
Benutzt für die <guimenuitem>Importieren von Amazon...</guimenuitem> Funktion.
</para></listitem>
<listitem><para><guilabel>DiscogsImport</guilabel>:
Benutzt für die <guimenuitem>Importieren von Discogs...</guimenuitem> Funktion.
</para></listitem>
<listitem><para><guilabel>FreedbImport</guilabel>:
Benutzt für die <guimenuitem>Importieren von gnudb.org...</guimenuitem>
und <guimenuitem>Importieren von TrackType.org...</guimenuitem> Funktionen.
</para></listitem>
<listitem><para><guilabel>MusicBrainzImport</guilabel>:
Benutzt für die <guimenuitem>Importieren von MusicBrainz-Album...</guimenuitem>
Funktion.
</para></listitem>
<listitem><para><guilabel>AcoustidImport</guilabel>:
Benutzt für die <guimenuitem>Importieren von MusicBrainz-Fingerprint...</guimenuitem>
Funktion, welche von den Bibliotheken
<ulink url="http://acoustid.org/chromaprint">Chromaprint</ulink>
und <ulink url="http://libav.org/">libav</ulink> abhängig ist.
</para></listitem>
</itemizedlist>
</para>
<para>
Deaktivierte Erweiterungen werden nicht geladen, damit lässt sich also der
Speicherverbrauch und die Ladezeit optimieren. Die Einstellungen auf dieser
Seite werden aber erst nach einem Neustart von &kid3; aktiv.
</para>
</listitem>
</varlistentry>

<varlistentry id="configure-shortcuts">
<term><menuchoice>
<guimenu>Einstellungen</guimenu>
<guimenuitem>Kurzbefehle festlegen...</guimenuitem>
</menuchoice></term>
<listitem><para>Öffnet einen Dialog, um den meisten Programm-Funktionen
ein Tastatur-Kürzel zuzuordnen. Es gibt sogar einige Funktionen ohne
entsprechenden Menüpunkt oder Knopf, z.B. nächste Datei, vorangehende Datei,
alles auswählen.
</para>
<para>
</para>
</listitem>
</varlistentry>

</variablelist>
</para>

</sect1>

<sect1 id="help-menu">
<title>Das Menü Hilfe</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Hilfe</guimenu>
<guimenuitem>Handbuch zu Kid3</guimenuitem>
</menuchoice></term>
<listitem><para><action>Öffnet dieses Handbuch.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Hilfe</guimenu>
<guimenuitem>Über Kid3</guimenuitem>
</menuchoice></term>
<listitem><para><action>Zeigt eine kurze Information über Kid3 an.
</action></para></listitem>
</varlistentry>


</variablelist>
</para>

</sect1>

</chapter>

<chapter id="kid3-cli">
<title>kid3-cli</title>
<sect1 id="kid3-cli-commands">
<title>Befehle</title>
<para>
<command>kid3-cli</command> bietet eine Kommandozeile für &kid3;. Wenn ein
Verzeichnispfad als Parameter verwendet wird, so wird das Verzeichnis
geöffnet. Bei einem oder mehreren Dateipfaden wird das übergeordnete
Verzeichnis geöffnet, und die Dateien werden ausgewählt. Befehle werden dann
auf diese Dateien angewendet. Befehle werden mit <option>-c</option> Optionen
angegeben, wenn mehrere vorhanden sind, so werden sie der Reihe nach
ausgeführt. Falls Dateien durch die Befehle verändert werden, so werden sie am
Ende gespeichert. Wenn keine Befehlsoptionen vorhanden sind, so startet
<command>kid3-cli</command> im interaktiven Modus. Dort können Befehle
eingegeben werden, welche auf die ausgewählten Dateien angewendet werden. Die
folgenden Abschnitte beschreiben alle verfügbaren Befehle.
</para>

<sect2 id="cli-help">
<title>Hilfe</title>
<cmdsynopsis>
<command>help</command>
<arg><replaceable>BEFEHLSNAME</replaceable></arg>
</cmdsynopsis>
<para>Zeigt Hilfe über die Parameter von
<replaceable>BEFEHLSNAME</replaceable> oder über alle Befehle falls kein
Befehlsname angegeben wird.
</para>
</sect2>

<sect2 id="cli-timeout">
<title>Zeitüberschreitung</title>
<cmdsynopsis>
<command>timeout</command>
<group>
<arg choice="plain">default</arg>
<arg choice="plain">off</arg>
<arg choice="plain"><replaceable>ZEIT</replaceable></arg>
</group>
</cmdsynopsis>
<para>Überschreibt den Wert für die maximal erlaubte Ausführungszeit der
Befehle. Die Befehle werden nach einer spezifischen Zeit abgebrochen, nach 10
Sekunden bei <command>ls</command> und <command>albumart</command>, 60
Sekunden bei <command>autoimport</command> und <command>filter</command> und 3
Sekunden für alle anderen Befehle. Wenn eine grosse Anzahl von Dateien
bearbeitet wird, so können diese Maximalzeiten zu restriktiv sein. Daher kann
mit diesem Befehl der Timeout für alle Befehle auf
<replaceable>ZEIT</replaceable> ms gesetzt werden, gänzlich abgeschaltet
werden oder auf den Voreinstellungen belassen werden.
</para>
</sect2>

<sect2 id="cli-exit">
<title>Anwendung beenden</title>
<cmdsynopsis>
<command>exit</command>
<arg>force</arg>
</cmdsynopsis>
<para>Beendet die Anwendung. Falls veränderte Dateien existieren, so muss der
Parameter <parameter class="command">force</parameter> mitgegeben werden.
</para>
</sect2>

<sect2 id="cli-cd">
<title>Verzeichnis wechseln</title>
<cmdsynopsis>
<command>cd</command>
<arg><replaceable>VERZEICHNIS</replaceable></arg>
</cmdsynopsis>
<para>Wenn kein <replaceable>VERZEICHNIS</replaceable> angegeben wird, so wird
ins Benutzerverzeichnis gewechselt, sonst in das angegebene Verzeichnis. Bei
einem oder mehreren Dateipfaden wird das übergeordnete Verzeichnis geöffnet,
und die Dateien werden ausgewählt.
</para>
</sect2>

<sect2 id="cli-pwd">
<title>Aktuelles Verzeichnis ausgeben</title>
<cmdsynopsis>
<command>pwd</command>
</cmdsynopsis>
<para>Gibt den Pfad des aktuellen Verzeichnisses aus.</para>
</sect2>

<sect2 id="cli-ls">
<title>Verzeichnisliste</title>
<cmdsynopsis>
<command>ls</command>
</cmdsynopsis>
<para>Zeigt den Inhalt des aktuellen Verzeichnisses an. Dies entspricht der
Dateiliste im &kid3; GUI. Vier Zeichen auf der linken Seite des Dateinamens
zeigen Zustandsinformationen an.
</para>

<itemizedlist>
<listitem><para><computeroutput>&gt;</computeroutput> Datei ist ausgewählt.
</para></listitem>
<listitem><para><computeroutput>*</computeroutput> Datei ist verändert.
</para></listitem>
<listitem><para><computeroutput>1</computeroutput> Datei hat ein Tag 1,
sonst wird '<computeroutput>-</computeroutput>' angezeigt.</para></listitem>
<listitem><para><computeroutput>2</computeroutput> Datei hat ein Tag 2,
sonst wird '<computeroutput>-</computeroutput>' angezeigt.</para></listitem>
</itemizedlist>

<screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
  1- 01 Intro.mp3
> 12 02 We Only Got This One.mp3
 *1- 03 Outro.mp3</computeroutput></screen>

<para>In diesem Beispiel haben alle Dateien ein Tag 1, die zweite Datei hat
auch ein Tag 2 und ist ausgewählt. Die dritte Datei ist verändert.
</para>
</sect2>

<sect2 id="cli-save">
<title>Veränderte Dateien speichern</title>
<cmdsynopsis>
<command>save</command>
</cmdsynopsis>
<para>
</para>
</sect2>

<sect2 id="cli-select">
<title>Datei wählen</title>
<cmdsynopsis>
<command>select</command>
<group>
<arg choice="plain">all</arg>
<arg choice="plain">none</arg>
<arg choice="plain">first</arg>
<arg choice="plain">previous</arg>
<arg choice="plain">next</arg>
<arg choice="plain" rep="repeat"><replaceable>DATEI</replaceable></arg>
</group>
</cmdsynopsis>
<para>Alle Dateien werden mit <userinput>select all</userinput> ausgewählt,
mit <userinput>select none</userinput> wird die Selektion aufgehoben. Um die
Dateien des aktuellen Verzeichnisses zu traversieren, wird mit
<userinput>select first</userinput> gestartet, vorwärts geht es mit
<userinput>select next</userinput> und rückwärts mit <userinput>select
previous</userinput>. Dateien können über ihren Namen zur Auswahl hinzugefügt
werden. Wildcards sind möglich, so werden mit <userinput>select
*.mp3</userinput> alle MP3-Dateien im aktuellen Verzeichnis ausgewählt.
</para>

<screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>select first</userinput>
<prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
> 1- 01 Intro.mp3
  12 02 We Only Got This One.mp3
 *1- 03 Outro.mp3</computeroutput>
<prompt>kid3-cli&gt; </prompt><userinput>select next</userinput>
<prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
  1- 01 Intro.mp3
> 12 02 We Only Got This One.mp3
 *1- 03 Outro.mp3</computeroutput>
<prompt>kid3-cli&gt; </prompt><userinput>select *.mp3</userinput>
<prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
> 1- 01 Intro.mp3
> 12 02 We Only Got This One.mp3
>*1- 03 Outro.mp3</computeroutput></screen>
</sect2>

<sect2 id="cli-tag">
<title>Tag auswählen</title>
<cmdsynopsis>
<command>tag</command>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Viele Befehle haben einen optionalen <replaceable>TAGNUMMERN</replaceable>
Parameter, welcher festlegt, ob der Befehl auf Tag 1 oder 2 wirkt. Wenn dieser
Parameter weggelassen wird, so werden die standardmäßigen Tagnummern
verwendet, welche mit dem Befehl <command>tag</command> festgelegt werden
können. Voreingestellt ist ein Wert von <literal>12</literal>, was bedeutet,
dass Informationen vom Tag 2 geholt werden, falls es vorhanden ist, sonst vom
Tag 1. Änderungen werden am Tag 2 durchgeführt. Die
<option><replaceable>TAGNUMMERN</replaceable></option> können auf
<userinput>1</userinput> oder <userinput>2</userinput> gesetzt werden, damit
nur das entsprechende Tag verwendet wird. Wird kein Parameter angegeben, so
wird die momentane Einstellung angezeigt.
</para>
</sect2>

<sect2 id="cli-get">
<title>Tag-Element holen</title>
<cmdsynopsis>
<command>get</command>
<group>
<arg choice="plain">all</arg>
<arg choice="plain"><replaceable>ELEMENTNAME</replaceable></arg>
</group>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Dieser Befehl kann dazu benutzt werden, den Wert eines bestimmten
Tag-Elements zu lesen oder um Informationen über alle Tag-Elemente zu holen
(wenn kein Parameter vorhanden ist oder <option>all</option> verwendet
wird). Veränderte Elemente werden mit einem
'<computeroutput>*</computeroutput>' markiert.
</para>

<screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>get</userinput><computeroutput>
Datei: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
  Name: 01 Intro.mp3
Tag 1: ID3v1.1
  Titel         Intro
  Interpret     One Hit Wonder
  Album         Let's Tag
  Datum         2013
  Tracknummer   1
  Genre         Pop</computeroutput>
<prompt>kid3-cli&gt; </prompt><userinput>get title</userinput><computeroutput>
Intro</computeroutput></screen>
<para>Ein Bild kann in einer Datei gespeichert werden.
<screen width="65"><userinput>get picture:"/pfad/zu/folder.jpg"</userinput></screen>
</para>
<para>Synchronisierter Liedtext wird im LRC-Format exportiert.
<screen width="65"><userinput>get SYLT:"/pfad/zu/lyrics.lrc"</userinput></screen>
</para>
</sect2>

<sect2 id="cli-set">
<title>Tag-Element setzen</title>
<cmdsynopsis>
<command>set</command>
<arg choice="req"><replaceable>ELEMENTNAME</replaceable></arg>
<arg choice="req"><replaceable>ELEMENTWERT</replaceable></arg>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Dieser Befehl setzt den Wert eines bestimmten Tag-Elements.
</para>
<screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>set remixer "O.H. Wonder"</userinput></screen>
<para>Um den Inhalt eines Bild-Elements aus einer Datei zu befüllen, kann
<screen width="65"><userinput>set picture:"/pfad/zu/folder.jpg" "Bildbeschreibung"</userinput></screen>
verwendet werden.
</para>
<para>Synchronisierter Liedtext kann aus einer LRC-Datei importiert werden.
<screen width="65"><userinput>set SYLT:"/pfad/zu/lyrics.lrc" "Beschreibung"</userinput></screen>
</para>
</sect2>

<sect2 id="cli-revert">
<title>Änderungen rückgängig machen</title>
<cmdsynopsis>
<command>revert</command>
</cmdsynopsis>
<para>Macht alle Änderungen an den ausgewählten Dateien rückgängig (oder an
allen Dateien, falls keine selektiert sind).
</para>
</sect2>

<sect2 id="cli-import">
<title>Von Datei oder Zwischenablage importieren</title>
<cmdsynopsis>
<command>import</command>
<arg choice="req"><replaceable>DATEI</replaceable></arg>
<arg choice="req"><replaceable>FORMATNAME</replaceable></arg>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Die Tags werden aus <replaceable>DATEI</replaceable> importiert (oder
von der Zwischenablage falls <userinput>clipboard</userinput> für
<replaceable>DATEI</replaceable> angegeben wird) im Format
<replaceable>FORMATNAME</replaceable> (z.B. <userinput>"CSV
unquoted"</userinput>, siehe <link linkend="import-text">Importieren</link>).
</para>
</sect2>

<sect2 id="cli-autoimport">
<title>Automatisch importieren</title>
<cmdsynopsis>
<command>autoimport</command>
<arg><replaceable>PROFILNAME</replaceable></arg>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Es wird automatisch importiert unter Verwendung des Profils
<replaceable>PROFILNAME</replaceable> (siehe <link
linkend="batch-import">Automatisch importieren</link>,
<userinput>"All"</userinput> wird benutzt, falls kein Profil angegeben
wird).
</para>
</sect2>

<sect2 id="cli-albumart">
<title>Cover-Bilder herunterladen</title>
<cmdsynopsis>
<command>albumart</command>
<arg choice="req"><replaceable>URL</replaceable></arg>
<arg>all</arg>
</cmdsynopsis>
<para>Setzt das Albumcover mit einem von <replaceable>URL</replaceable>
heruntergeladenen Bild. Die Regeln zur Umwandlung einer allgemeinen URL
(z.B. von Amazon) zu einer Bild-URL werden verwendet, diese können im <link
linkend="browse_pictures">Nach Cover-Bildern suchen</link> Dialog definiert
werden. Um das Albumcover mit einer lokalen Datei zu setzen kann der <link
linkend="cli-set">set</link> Befehl verwendet werden.
</para>
<screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>albumart
http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC</userinput></screen>
</sect2>

<sect2 id="cli-export">
<title>In Datei oder Zwischenablage exportieren</title>
<cmdsynopsis>
<command>export</command>
<arg choice="req"><replaceable>DATEI</replaceable></arg>
<arg choice="req"><replaceable>FORMATNAME</replaceable></arg>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Tags werden in die Datei <replaceable>DATEI</replaceable> exportiert
(oder in die Zwischenablage, falls <userinput>clipboard</userinput> für
<replaceable>DATEI</replaceable> angegeben wird) im Format
<replaceable>FORMATNAME</replaceable> (z.B. <userinput>"CSV
unquoted"</userinput>, siehe <link linkend="export">Exportieren</link>).
</para>
</sect2>

<sect2 id="cli-playlist">
<title>Stückliste erstellen</title>
<cmdsynopsis>
<command>playlist</command>
</cmdsynopsis>
<para>Erstellt eine Stückliste in dem in der Konfiguration gesetzten Format,
siehe <link linkend="create-playlist">Stückliste erstellen</link>.
</para>
</sect2>

<sect2 id="cli-filenameformat">
<title>Dateinamenformat anwenden</title>
<cmdsynopsis>
<command>filenameformat</command>
</cmdsynopsis>
<para>Wendet das Dateinamenformat an, welches in der Konfiguration gesetzt ist,
siehe <link linkend="apply-filename-format">Dateinamenformat anwenden</link>.
</para>
</sect2>

<sect2 id="cli-tagformat">
<title>Tag-Format anwenden</title>
<cmdsynopsis>
<command>tagformat</command>
</cmdsynopsis>
<para>Wendet das Tag-Format an, welches in der Konfiguration gesetzt ist,
siehe <link linkend="apply-tag-format">Tag-Format anwenden</link>.
</para>
</sect2>

<sect2 id="cli-textencoding">
<title>Textkodierung anwenden</title>
<cmdsynopsis>
<command>textencoding</command>
</cmdsynopsis>
<para>Wendet die Textkodierung an, welche in der Konfiguration gesetzt ist,
siehe <link linkend="apply-text-encoding">Textkodierung anwenden</link>.
</para>
</sect2>

<sect2 id="cli-renamedir">
<title>Verzeichnis umbenennen</title>
<cmdsynopsis>
<command>renamedir</command>
<arg><replaceable>FORMAT</replaceable></arg>
<group>
<arg choice="plain">create</arg>
<arg choice="plain">rename</arg>
<arg choice="plain">dryrun</arg>
</group>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Mit diesem Befehl werden Verzeichnisse umbenannt oder neu erstellt
anhand der Werte in den Tags nach einem bestimmten
<replaceable>FORMAT</replaceable> (z.B. <userinput>%{artist} -
%{album}</userinput>, siehe <link linkend="rename-directory">Verzeichnis
umbenennen</link>), wenn kein Format angegeben wird, so wird dasjenige
verwendet, welches im <guilabel>Verzeichnis umbenennen</guilabel> Dialog
gesetzt ist. Normalerweise wird der Modus <option>rename</option> verwendet;
um neue Verzeichnisse zu erstellen, muss <option>create</option> explizit
angegeben werden. Die zum Umbenennen nötigen Aktionen werden sofort
ausgeführt, um bloß eine Vorschau über diese Aktionen zu sehen, kann die
<option>dryrun</option> Option verwendet werden.
</para>
</sect2>

<sect2 id="cli-numbertracks">
<title>Tracks nummerieren</title>
<cmdsynopsis>
<command>numbertracks</command>
<arg><replaceable>TRACKNUMMER</replaceable></arg>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Nummeriert die ausgewählten Dateien beginnend mit
<replaceable>TRACKNUMMER</replaceable> (<literal>1</literal> wenn nichts
angegeben wird).
</para>
</sect2>

<sect2 id="cli-filter">
<title>Filter</title>
<cmdsynopsis>
<command>filter</command>
<group>
<arg choice="plain"><replaceable>FILTERNAME</replaceable></arg>
<arg choice="plain"><replaceable>FILTERFORMAT</replaceable></arg>
</group>
</cmdsynopsis>
<para>Filtert die Dateien, so dass nur Dateien angezeigt werden, welche dem
<replaceable>FILTERFORMAT</replaceable> entsprechen. Der Name eines
vordefinierten Filterausdrucks (z.B. <userinput>"Filename Tag
Mismatch"</userinput>) kann anstelle eines Filterausdrucks verwendet werden,
siehe <link linkend="filter">Filter</link>.
</para>

<screen width="65"><prompt>kid3-cli&gt; </prompt><userinput>filter '%{title} contains "tro"'</userinput><computeroutput>
Begonnen
  /home/urs/One Hit Wonder - Let's Tag
+ 01 Intro.mp3
- 02 We Only Got This One.mp3
+ 03 Outro.mp3
Fertig</computeroutput>
<prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
  1- 01 Intro.mp3
  1- 03 Outro.mp3</computeroutput>
<prompt>kid3-cli&gt; </prompt><userinput>filter All</userinput><computeroutput>
Begonnen
  /home/urs/One Hit Wonder - Let's Tag
+ 01 Intro.mp3
+ 02 We Only Got This One.mp3
+ 03 Outro.mp3
Fertig</computeroutput>
<prompt>kid3-cli&gt; </prompt><userinput>ls</userinput><computeroutput>
  1- 01 Intro.mp3
  12 02 We Only Got This One.mp3
  1- 03 Outro.mp3</computeroutput></screen>
</sect2>

<sect2 id="cli-to24">
<title>ID3v2.3 nach ID3v2.4 konvertieren</title>
<cmdsynopsis>
<command>to24</command>
</cmdsynopsis>
</sect2>

<sect2 id="cli-to23">
<title>ID3v2.4 nach ID3v2.3 konvertieren</title>
<cmdsynopsis>
<command>to23</command>
</cmdsynopsis>
</sect2>

<sect2 id="cli-fromtag">
<title>Dateiname von Tag</title>
<cmdsynopsis>
<command>fromtag</command>
<arg><replaceable>FORMAT</replaceable></arg>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Setzt die Dateinamen der ausgewählten Dateien anhand der Werte in den
Tags, z.B. <userinput>fromtag "%{track} - %{title}" 1</userinput>. Wenn kein
Format angegeben wird, wird dasjenige verwendet, welches im GUI gesetzt ist.
</para>
</sect2>

<sect2 id="cli-totag">
<title>Tag von Dateiname</title>
<cmdsynopsis>
<command>totag</command>
<arg><replaceable>FORMAT</replaceable></arg>
<arg><replaceable>TAGNUMMERN</replaceable></arg>
</cmdsynopsis>
<para>Setzt die Tag-Elemente anhand der Dateinamen, z.B. <userinput>totag
"%{albumartist} - %{album}/%{track} %{title}" 2</userinput>. Wenn kein
Format angegeben wird, wird dasjenige verwendet, welches im GUI gesetzt ist.
Falls der Dateiname nicht diesem Format entspricht, werden noch
einige andere, gängige Formate ausprobiert.
</para>
</sect2>

<sect2 id="cli-syncto">
<title>Tag zu anderem Tag</title>
<cmdsynopsis>
<command>syncto</command>
<arg choice="req"><replaceable>TAGNUMMER</replaceable></arg>
</cmdsynopsis>
<para>Kopiert die Tag-Elemente von einem Tag zum anderen Tag, um
beispielsweise das ID3v2 Tag anhand der Werte im ID3v1 Tag zu setzen, wird
<userinput>syncto 2</userinput> verwendet.
</para>
</sect2>

<sect2 id="cli-copy">
<title>Kopieren</title>
<cmdsynopsis>
<command>copy</command>
<arg><replaceable>TAGNUMMER</replaceable></arg>
</cmdsynopsis>
<para>Kopiert die Tag-Elemente der selektierten Datei in die interne
Ablage. Sie können dann in einer anderen Datei mit dem
<command>paste</command> Befehl gesetzt werden.
</para>
</sect2>

<sect2 id="cli-paste">
<title>Einfügen</title>
<cmdsynopsis>
<command>paste</command>
<arg><replaceable>TAGNUMMER</replaceable></arg>
</cmdsynopsis>
<para>Setzt die Tag-Elemente gemäß dem Inhalt der <command>copy</command>
Ablage in den ausgewählten Dateien.
</para>
</sect2>

<sect2 id="cli-remove">
<title>Entfernen</title>
<cmdsynopsis>
<command>remove</command>
<arg><replaceable>TAGNUMMER</replaceable></arg>
</cmdsynopsis>
<para>Entfernt ein Tag.
</para>
</sect2>

<sect2 id="cli-play">
<title>Wiedergabe</title>
<cmdsynopsis>
<command>play</command>
<group>
<arg choice="plain">pause</arg>
<arg choice="plain">stop</arg>
<arg choice="plain">previous</arg>
<arg choice="plain">next</arg>
</group>
</cmdsynopsis>
<para>Startet die Wiedergabe, danach kann sie mit den Optionen
<option>pause</option> (um zu pausieren und weiterzufahren),
<option>stop</option>, <option>previous</option> und <option>next</option>
kontrolliert werden.
</para>
</sect2>

</sect1>

<sect1 id="kid3-cli-examples">
<title>Beispiele</title>
<para>Setze das Albumcover in allen Dateien eines Verzeichnisses unter
Verwendung der automatischen Import-Funktion:</para>
<screen width="65"><userinput>kid3-cli -c 'autoimport "Cover Art"' /pfad/zum/verzeichnis</userinput></screen>

<para>Entferne Kommentar und wende Tag-Format an für beide Tags in allen
MP3-Dateien eines Verzeichnisses:</para>
<screen width="65"><userinput>kid3-cli -c 'set comment "" 1' -c 'set comment "" 2' \
-c 'tagformat 1' -c 'tagformat 2' /pfad/zum/verzeichnis/*.mp3</userinput></screen>

<para>Automatischer Import in Tag 2, auch ins Tag 1 kopieren, die Dateinamen
aus Tag 2 setzen und schließlich eine Stückliste erstellen:</para>
<screen width="65"><userinput>kid3-cli -c autoimport -c 'syncto 1' -c fromtag -c playlist \
  /pfad/zum/verzeichnis/*.mp3</userinput></screen>

<para>Für alle Dateien mit einem ID3v2.4.0 Tag, dieses nach ID3v2.3.0
konvertieren und das Arrangierung Element entfernen:</para>
<screen width="65"><userinput>kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
  -c "set arranger ''" /pfad/zum/verzeichnis</userinput></screen>

<para>Dieses Python-Skript erzeugt mit <command>kid3-cli</command> iTunes
Sound Check iTunNORM Frames aus Replay Gain Information.</para>
<programlisting>
<![CDATA[
#!/usr/bin/env python
# Generate iTunes Sound Check from ReplayGain.
from __future__ import print_function
import os, sys, subprocess

def rg2sc(dirpath):
  for root, dirs, files in os.walk(dirpath):
    for name in files:
      if name.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
        fn = os.path.join(root, name)
        rg = subprocess.check_output([
          'kid3-cli', '-c', 'get "replaygain_track_gain"',
           fn]).strip()
        if rg.endswith(b' dB'):
          rg = rg[:-3]
        try:
          rg = float(rg)
        except ValueError:
          print('Value %s of %s in not a float' % (rg, fn))
          continue
        sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
        subprocess.call([
          'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])

if __name__ == '__main__':
  rg2sc(sys.argv[1])
]]>
</programlisting>
</sect1>
</chapter>

<chapter id="credits">

<title>Danksagungen und Lizenz</title>

<para>
&kid3;
</para>
<para>
Programmiert von Urs Fleisch <email>ufleisch@users.sourceforge.net</email>
</para>

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kid3">
<title>Bezugsquellen</title>

<para>
&kid3; ist zu finden unter
<ulink url="http://kid3.sourceforge.net">http://kid3.sourceforge.net</ulink>.
</para>
</sect1>

<sect1 id="requirements">
<title>Anforderungen</title>

<para>
&kid3; braucht <ulink url="http://qt-project.org/">Qt</ulink>. <ulink
url="http://www.kde.org">KDE</ulink> ist empfohlen aber nicht notwendig,
denn &kid3; kann auch als reine Qt Applikation kompiliert werden. &kid3;
läuft auf Systemen, wo diese Programmbibliotheken vorhanden sind,
z.B. auf GNU/Linux, Windows und Mac OS X.
Um Ogg/Vorbis Dateien zu taggen werden
<ulink url="http://xiph.org/ogg/">libogg</ulink>,
<ulink url="http://xiph.org/vorbis/">libvorbis und libvorbisfile</ulink>
benötigt, für FLAC Dateien <ulink url="http://flac.sourceforge.net">libFLAC++
und libFLAC</ulink>. Für MP3 Dateien
wird die <ulink url="http://id3lib.sourceforge.net">id3lib</ulink>
verwendet.
Für diese vier Formate kann auch
die <ulink url="http://taglib.github.io/">TagLib</ulink>
verwendet werden, welche zudem auch Opus, MPC, APE, MP2, Speex, TrueAudio, WavPack,
WMA, WAV, AIFF Dateien und Tracker Module unterstützt.
Für das Importieren über akustische Fingerabdrücke
werden <ulink url="http://acoustid.org/chromaprint">Chromaprint</ulink>
und <ulink url="http://libav.org/">libav</ulink> verwendet.
</para>
<para>
&kid3; ist für die meisten Linux-Distributionen, Windows und Mac OS X
erhältlich. Links finden sich auf <ulink url="http://kid3.sourceforge.net">
http://kid3.sourceforge.net</ulink>.
</para>

</sect1>

<sect1 id="compilation">
<title>Kompilieren und Installation</title>

<para>
Man kann &kid3; mit oder ohne KDE kompilieren. Ohne KDE ist &kid3; eine reine
Qt Applikation und es fehlen einige Konfigurations- und Session-Funktionen.
</para>
<para>
Für die KDE Version wird im obersten Verzeichnis getippt:
<screen width="40">
<prompt>%</prompt> <userinput>cmake .</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>
<para>
Falls nicht alle Programmbibliotheken vorhanden sind, so wird &kid3; mit
reduzierter Funktionalität kompiliert. Es sollte also darauf geachtet werden,
dass die Entwicklungspakete aller gewünschten Bibliotheken auch installiert
sind. Andererseits kann mit <userinput>cmake</userinput>-Optionen bestimmt
werden, was verwendet werden soll. Die Voreinstellung ist
<userinput>-D WITH_TAGLIB:BOOL=ON -D WITH_MP4V2:BOOL=OFF -D WITH_ID3LIB:BOOL=ON
-D WITH_CHROMAPRINT:BOOL=ON -D WITH_VORBIS:BOOL=ON -D WITH_FLAC:BOOL=ON
</userinput>. Entsprechend kann auch
<userinput>OFF</userinput> gesetzt werden.
</para>
<para>
Um &kid3; als Qt Applikation ohne KDE zu kompilieren, wird die
<userinput>cmake</userinput> Option <userinput>-DWITH_APPS=Qt</userinput> benutzt.
Um sowohl eine KDE als auch eine Qt Applikation zu kompilieren, wird
<userinput>-DWITH_APPS="Qt;KDE"</userinput> gesetzt.
</para>
<para>
Qt 4 oder Qt 5 können verwendet werden. Um Qt 4 zu erzwingen, kann
<userinput>-DWITH_QT4=ON</userinput> gesetzt werden, entsprechend
<userinput>-DWITH_QT5=ON</userinput> für Qt 5, wenn beide Optionen
ausgeschaltet sind (Standardeinstellung), so wird Qt 4 bevorzugt, wenn beide
Versionen installiert sind. Um eine bestimmte Qt-Installation zu nutzen, kann
<userinput>-DQT_QMAKE_EXECUTABLE=/Pfad/zu/qmake</userinput> gesetzt werden.
Wenn die KDE Applikation eingeschaltet ist, so wird mit Qt 4 KDE 4 verwendet
und mit Qt 5 KDE 5.
</para>
<para>
Für die Erzeugung von RPM-Paketen ist die Datei <filename>kid3.spec</filename>
vorhanden, für Debian-Pakete steht das Skript
<filename>build-deb.sh</filename> zur Verfügung.
</para>

<para>
Die Qt Anwendung kann auch unter Windows und Mac OS X kompiliert werden.
Die Verzeichnisse <filename>win32</filename> und <filename>macosx</filename>
beinhalten Skripte zum Kompilieren und Erzeugen von Paketen. Das Skript
<filename>buildlibs.sh</filename> erstellt die notwendigen Programmbibliotheken.
</para>

</sect1>

<sect1 id="configuration">
<title>Konfiguration</title>

<para>Mit KDE werden der Dateinamenfilter, das Dateinamenformat, die
Importformate, die Dateinamen- und ID3-Formate, die
Einstellungen für die Werkzeug- und Statusleiste sowie die Fenstergröße im
Standardverzeichnis in der Datei <filename>kid3rc</filename> gespeichert.
Als Qt-Anwendung liegt diese Datei
in <filename>.config/Kid3/Kid3.conf</filename>. Unter
Windows wird die Konfiguration in der Registry gespeichert.
</para>

</sect1>

</appendix>

<appendix id="dbus-interface">
<title>D-Bus Schnittstelle</title>

<sect1 id="dbus-examples">
<title>D-Bus Beispiele</title>

<para>
Die Qt 4 und KDE 4 Versionen unter Linux bieten eine D-Bus Schnittstelle, mit
welcher Kid3 über Skripte gesteuert werden kann. Skripte können in jeder
Sprache, für die D-Bus-Anbindungen existieren, geschrieben werden (z.B. in
Python) und können über die <guilabel>Benutzerbefehle</guilabel> die
Funktionalität von &kid3; erweitern.
</para>

<para>
Mit folgenden Befehlen kann der Interpret im Tag 2 auf den Wert "One Hit
Wonder" gesetzt werden:
</para>

<variablelist>
<varlistentry><term>Shell</term>
<listitem>
<programlisting>
dbus-send --dest=net.sourceforge.kid3 --print-reply=literal \
/Kid3 net.sourceforge.Kid3.setFrame int32:2 string:'Artist' \
string:'One Hit Wonder'
</programlisting>
<para>
oder einfacher mit <command>qdbus</command> von Qt
(<command>qdbusviewer</command> kann benutzt werden, um die D-Bus
Schnittstelle über eine grafische Benutzeroberfläche zu erkunden):
</para>
<programlisting>
qdbus net.sourceforge.kid3 /Kid3 setFrame 2 Artist \
'One Hit Wonder'
</programlisting>
</listitem>
</varlistentry>
<varlistentry><term>Python</term>
<listitem>
<programlisting>
import dbus
kid3 = dbus.SessionBus().get_object(
  'net.sourceforge.kid3', '/Kid3')
kid3.setFrame(2, 'Artist', 'One Hit Wonder')
</programlisting>
</listitem>
</varlistentry>
<varlistentry><term>Perl</term>
<listitem>
<programlisting>
use Net::DBus;
$kid3 = Net::DBus->session->get_service(
  "net.sourceforge.kid3")->get_object(
  "/Kid3", "net.sourceforge.Kid3");
$kid3->setFrame(2, "Artist", "One Hit Wonder");
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="dbus-api">
<title>D-Bus API</title>

<para>
Das D-Bus API ist in <filename>net.sourceforge.Kid3.xml</filename>
spezifiziert. Die Kid3 Schnittstelle hat die folgenden Methoden:
</para>

<sect2 id="dbus-openDirectory">
<title>Öffne Datei oder Verzeichnis</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>openDirectory</function></funcdef>
  <paramdef>string <parameter>path</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>path</replaceable></term>
    <listitem><para>Pfad zu Datei oder Verzeichnis</para></listitem>
  </varlistentry>
</variablelist>
<para>Wenn OK wird true zurückgegeben.</para>
</sect2>

<sect2 id="dbus-save">
<title>Speichere alle veränderten Dateien</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>save</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Wenn OK wird true zurückgegeben.</para>
</sect2>

<sect2 id="dbus-getErrorMessage">
<title>Detaillierte Fehlermeldung für einige Methoden</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getErrorMessage</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt eine detaillierte Fehlermeldung zurück.</para>
</sect2>

<sect2 id="dbus-revert">
<title>Änderungen an Dateien rückgängig machen</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>revert</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-batchImport">
<title>Automatischen Import starten</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>batchImport</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
  <paramdef>string <parameter>profileName</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Maske (Bit 0 für Tag 1, Bit 1 für Tag 2)</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>profileName</replaceable></term>
    <listitem><para>Name des zu verwendenden Profils</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-importFromFile">
<title>Tags von Datei importieren</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>importFromFile</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
  <paramdef>string <parameter>path</parameter></paramdef>
  <paramdef>int32 <parameter>fmtIdx</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>path</replaceable></term>
    <listitem><para>Pfad zu Datei</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>fmtIdx</replaceable></term>
    <listitem><para>Format Index</para></listitem>
  </varlistentry>
</variablelist>
<para>Wenn OK wird true zurückgegeben.</para>
</sect2>

<sect2 id="dbus-downloadAlbumArt">
<title>Cover-Bild herunterladen</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>downloadAlbumArt</function></funcdef>
  <paramdef>string <parameter>url</parameter></paramdef>
  <paramdef>boolean <parameter>allFilesInDir</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>url</replaceable></term>
    <listitem><para>URL des Bildes oder einer dazugehörigen
    Website</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>allFilesInDir</replaceable></term>
    <listitem><para>falls true, wird das Bild in allen Dateien des
    Verzeichnisses hinzugefügt</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-exportToFile">
<title>Tags in Datei exportieren</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>exportToFile</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
  <paramdef>string <parameter>path</parameter></paramdef>
  <paramdef>int32 <parameter>fmtIdx</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>path</replaceable></term>
    <listitem><para>Pfad zu Datei</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>fmtIdx</replaceable></term>
    <listitem><para>Format Index</para></listitem>
  </varlistentry>
</variablelist>
<para>Wenn OK wird true zurückgegeben.</para>
</sect2>

<sect2 id="dbus-createPlaylist">
<title>Stückliste erstellen</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>createPlaylist</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Wenn OK wird true zurückgegeben.</para>
</sect2>

<sect2 id="dbus-quit">
<title>Anwendung beenden</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>quit</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-selectAll">
<title>Alles auswählen</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>selectAll</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-deselectAll">
<title>Gesamte Auswahl aufheben</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>deselectAll</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-firstFile">
<title>Gehe zur ersten Datei</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>firstFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt true zurück, wenn eine Datei existiert.</para>
</sect2>

<sect2 id="dbus-previousFile">
<title>Gehe zur vorangehende Datei</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>previousFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt true zurück, wenn eine vorangehende Datei existiert.</para>
</sect2>

<sect2 id="dbus-nextFile">
<title>Gehe zur nächstes Datei</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>nextFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt true zurück, wenn eine nächste Datei existiert.</para>
</sect2>

<sect2 id="dbus-selectFirstFile">
<title>Erste Datei auswählen</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>selectFirstFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt true zurück, wenn eine Datei existiert.</para>
</sect2>

<sect2 id="dbus-selectPreviousFile">
<title>Vorangehende Datei auswählen</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>selectPreviousFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt true zurück, wenn eine vorangehende Datei existiert.</para>
</sect2>

<sect2 id="dbus-selectNextFile">
<title>Nächste Datei auswählen</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>selectNextFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt true zurück, wenn eine nächste Datei existiert.</para>
</sect2>

<sect2 id="dbus-selectCurrentFile">
<title>Aktuelle Datei auswählen</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>selectCurrentFile</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt true zurück, wenn eine aktuelle Datei existiert.</para>
</sect2>

<sect2 id="dbus-expandDirectory">
<title>Aktuelles Verzeichnis auf- oder zuklappen</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>expandDirectory</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Ein Dateilistenelement ist ein Verzeichnis, wenn getFileName() einen
      Namen mit '/' als letztem Zeichen zurückgibt.</para>
<para>Gibt true zurück, wenn das aktuelle Dateilistenelement ein Verzeichnis ist.</para>
</sect2>

<sect2 id="dbus-applyFilenameFormat">
<title>Dateinamenformat anwenden</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>applyFilenameFormat</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-applyTagFormat">
<title>Tag Format anwenden</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>applyTagFormat</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-applyTextEncoding">
<title>Textkodierung anwenden</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>applyTextEncoding</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-setDirNameFromTag">
<title>Verzeichnisname von Tags setzen</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>setDirNameFromTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
  <paramdef>string <parameter>format</parameter></paramdef>
  <paramdef>boolean <parameter>create</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Maske (Bit 0 für Tag 1, Bit 1 für Tag 2)</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>format</replaceable></term>
    <listitem><para>Verzeichnisformat</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>create</replaceable></term>
    <listitem><para>true zum Erstellen, false zum Umbenennen</para></listitem>
  </varlistentry>
</variablelist>
<para>Wenn OK wird true zurückgegeben, sonst ist eine Fehlermeldung mit
      getErrorMessage() abrufbar.</para>
</sect2>

<sect2 id="dbus-numberTracks">
<title>Nummeriere Tracks in ausgewählten Dateien</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>numberTracks</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
  <paramdef>int32 <parameter>firstTrackNr</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Maske (Bit 0 für Tag 1, Bit 1 für Tag 2)</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>firstTrackNr</replaceable></term>
    <listitem><para>Nummer für erste Datei</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-filter">
<title>Dateien filtern</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>filter</function></funcdef>
  <paramdef>string <parameter>expression</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>expression</replaceable></term>
    <listitem><para>Filter Ausdruck</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-convertToId3v24">
<title>ID3v2.3 nach ID3v2.4 konvertieren</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>convertToId3v24</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-convertToId3v23">
<title>ID3v2.4 nach ID3v2.3 konvertieren</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>convertToId3v23</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Wenn OK wird true zurückgegeben.</para>
</sect2>

<sect2 id="dbus-getDirectoryName">
<title>Verzeichnispfad</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getDirectoryName</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt den absoluten Verzeichnispfad zurück.</para>
</sect2>

<sect2 id="dbus-getFileName">
<title>Dateiname</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getFileName</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Gibt den absoluten Dateinamen zurück, wenn es ein Verzeichnis ist, endet
      er mit "/".</para>
</sect2>

<sect2 id="dbus-setFileName">
<title>Setze Dateinamen</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setFileName</function></funcdef>
  <paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>name</replaceable></term>
    <listitem><para>Dateiname</para></listitem>
  </varlistentry>
</variablelist>
<para>Die Datei wird umbenannt, wenn das Verzeichnis gespeichert wird.</para>
</sect2>

<sect2 id="dbus-setFileNameFormat">
<title>Setze Format für Dateiname aus Tags</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setFileNameFormat</function></funcdef>
  <paramdef>string <parameter>format</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>format</replaceable></term>
    <listitem><para>Dateinamenformat</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-setFileNameFromTag">
<title>Generiere den Dateinamen aus den Tags</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setFileNameFromTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-getFrame">
<title>Wert eines Elementes</title>
<funcsynopsis>
<funcprototype>
  <funcdef>string <function>getFrame</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
  <paramdef>string <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>name</replaceable></term>
    <listitem><para>Elementname (z.B. "artist")</para></listitem>
  </varlistentry>
</variablelist>
<para>Um binäre Daten wie ein Bild von einem Element in einer Datei zu
speichern, kann der Dateiname dem Elementnamen hinzugefügt werden,
z.B. "Picture:/Pfad/zu/Datei". Auf dieselbe Weise kann synchronisierter
Liedtext exportiert werden, z.B. "SYLT:/Pfad/zu/Datei".</para>
<para>Gibt Wert des Elementes zurück.</para>
</sect2>

<sect2 id="dbus-setFrame">
<title>Setze Wert eines Elementes</title>
<funcsynopsis>
<funcprototype>
  <funcdef>boolean <function>setFrame</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
  <paramdef>string <parameter>name</parameter></paramdef>
  <paramdef>string <parameter>value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>name</replaceable></term>
    <listitem><para>Elementname (z.B. "artist")</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><replaceable>value</replaceable></term>
    <listitem><para>Wert des Elementes</para></listitem>
  </varlistentry>
</variablelist>
<para>Für Tag 2 (<parameter>tagMask</parameter> 2) gilt: Wenn kein Element
mit <parameter>name</parameter> existiert, so wird ein neues Element
hinzugefügt, wenn <parameter>value</parameter> leer ist, so wird das
Element gelöscht. Um binäre Daten wie ein Bild einem Element
hinzuzufügen, kann der Dateiname dem Elementnamen hinzugefügt werden,
z.B. "Picture:/Pfad/zu/Datei". "SYLT:/Pfad/zu/Datei" kann verwendet werden,
um synchronisierten Liedtext im LRC-Format zu importieren.</para>
<para>Wenn OK wird true zurückgegeben.</para>
</sect2>

<sect2 id="dbus-getTag">
<title>Alle Elemente eines Tags</title>
<funcsynopsis>
<funcprototype>
  <funcdef>array of string <function>getTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
</variablelist>
<para>Gibt eine Liste mit abwechselnd Elementnamen und -werten zurück.</para>
</sect2>

<sect2 id="dbus-getInformation">
<title>Technische Informationen über Datei</title>
<funcsynopsis>
<funcprototype>
  <funcdef>array of string <function>getInformation</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Eigenschaften sind Format, Bitrate, Samplerate, Channels, Duration,
      Channel Mode, VBR, Tag 1, Tag 2.
      Eigenschaften, welche nicht vorhanden sind, werden ausgelassen.</para>
<para>Gibt eine Liste mit abwechselnd Eigenschaftsnamen und -werten zurück.</para>
</sect2>

<sect2 id="dbus-setTagFromFileName">
<title>Setze Tag aus Dateinamen</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setTagFromFileName</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-setTagFromOtherTag">
<title>Setze Tag aus anderem Tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>setTagFromOtherTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-copyTag">
<title>Kopiere Tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>copyTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-pasteTag">
<title>Füge Tag ein</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>pasteTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-removeTag">
<title>Entferne Tag</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>removeTag</function></funcdef>
  <paramdef>int32 <parameter>tagMask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term><replaceable>tagMask</replaceable></term>
    <listitem><para>Tag Bit (1 für Tag 1, 2 für Tag 2)</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-reparseConfiguration">
<title>Lese die Konfiguration neu ein</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>reparseConfiguration</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para>Automatisierte Konfigurationsänderungen sind durch direktes Modifizieren
      der Konfigurationsdatei und anschließendes Einlesen möglich.</para>
</sect2>

<sect2 id="dbus-playAudio">
<title>Spielt die ausgewählten Dateien ab</title>
<funcsynopsis>
<funcprototype>
  <funcdef><function>playAudio</function></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

</sect1>

</appendix>

<appendix id="qml-interface">
<title>QML Schnittstelle</title>

<sect1 id="qml-examples">
<title>QML Beispiele</title>

<para>
QML Skripte lassen sich über das Kontextmenü der Dateiliste aufrufen und
in den Einstellungen auf der Seite <link
linkend="configure-user-actions-qml">Benutzerbefehle</link> setzen. Die 
dortigen Beispielskripte bieten eine Vorlage für die Programmierung eigener
Skripte. Codiert wird in JavaScript, hier das obligate "Hello World":
</para>

<programlisting>
import Kid3 1.0

Kid3Script {
  onRun: {
    console.log("Hello world, directory is", app.dirName)
    Qt.quit()
  }
}
</programlisting>

<para>
Wird dieses Skript unter <filename>/path/to/Example.qml</filename>
abgespeichert, so kann als Benutzerbefehl <command>@qml
/path/to/Example.qml</command> definiert werden. Wenn als Name <userinput>QML
Test</userinput> gesetzt und <guilabel>Ausgabe</guilabel> aktiviert wird,
so lässt sich das Skript über den Kontextmenüpunkt <guilabel>QML
Test</guilabel> der Dateiliste starten, und die Ausgabe ist im Fenster
sichtbar.
</para>

<para>
Alternativ lässt sich das Skript auch unabhängig von Kid3 mit den
QML-Werkzeugen starten.

<screen width="80">
qmlviewer -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
</screen>

Bei Qt 5 wird stattdessen
<screen width="80">
qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
</screen>
oder
<screen width="80">
qmlscene -I /usr/lib/kid3/plugins/imports /path/to/Example.qml
</screen>
verwendet. Bei Windows und OS X muss der Importpfad angepasst werden, damit er
auf <filename>imports</filename> bei den Plugins im
Installationsverzeichnis verweist. Außerhalb von Kid3 gestartete Skripte
verwenden das aktuelle Verzeichnis, es sollte also vorgängig in das gewünschte
Verzeichnis gewechselt werden.
</para>

<para>
Um die Titel im Tag 2 aller Dateien des aktuellen Verzeichnisses aufzulisten,
könnte folgendes Skript verwendet werden:
</para>

<programlisting>
import Kid3 1.0

Kid3Script {
  onRun: {
    app.firstFile()
    do {
      if (app.selectionInfo.tagFormatV2)
        console.log(app.getFrame(tagv2, "title"))
    } while (app.nextFile())
  }
}
</programlisting>

<para>
Wenn sich viele Dateien im Verzeichnis befinden, blockiert ein solches Skript
die Benutzeroberfläche für einige Zeit. Für längere Aktionen sollte man daher
kurze Pausen einlegen. Die unten stehende Alternative lagert die Arbeit an
einer einzelnen Datei in eine Funktion aus. Diese ruft sich am Ende mit
einem Timeout von 1 ms wieder selbst auf, sofern noch weitere Dateien zu
bearbeiten sind. Dadurch bleibt das GUI auch während dem Ablauf des Skripts
benutzbar.
</para>

<programlisting>
import Kid3 1.0

Kid3Script {
  onRun: {
    function doWork() {
      if (app.selectionInfo.tagFormatV2) {
        console.log(app.getFrame(tagv2, "title"))
      }
      if (!app.nextFile()) {
        Qt.quit()
      } else {
        setTimeout(doWork, 1)
      }
    }

    app.firstFile()
    doWork()
  }
}
</programlisting>

<para>
Weitere Beispiele sind bei &kid3; dabei und bereits bei den Benutzerbefehlen
eingetragen.

<itemizedlist>
<listitem><para>
<guilabel>ReplayGain to SoundCheck</guilabel>
(<filename>ReplayGain2SoundCheck.qml</filename>):
Erstellt iTunNORM SoundCheck Informationen aus Replay Gain Werten.
</para></listitem>
<listitem><para>
<guilabel>Resize Album Art</guilabel>
(<filename>ResizeAlbumArt.qml</filename>):
Skaliert eingebettete Bilder runter auf 500x500 Pixel.
</para></listitem>
<listitem><para>
<guilabel>Extract Album Art</guilabel>
(<filename>ExtractAlbumArt.qml</filename>):
Speichert alle eingebetteten Bilder als Dateien ab, ohne Duplikate zu
erzeugen.
</para></listitem>
<listitem><para>
<guilabel>Embed Album Art</guilabel>
(<filename>EmbedAlbumArt.qml</filename>):
Bettet Bilder aus Dateien in die Audio-Dateien ein, welche sich im selben
Ordner befinden.
</para></listitem>
<listitem><para>
<guilabel>Embed Lyrics</guilabel>
(<filename>EmbedLyrics.qml</filename>):
Holt unsynchronisierte Liedtexte von einem Webserver.
</para></listitem>
<listitem><para>
<guilabel>Text Encoding ID3v1</guilabel>
(<filename>ShowTextEncodingV1.qml</filename>):
Hilft dabei, die Codierung zu finden, indem es die ID3v1 Tags in allen
verfügbaren Zeichencodierungen anzeigt. 
</para></listitem>
<listitem><para>
<guilabel>Export CSV</guilabel>
(<filename>ExportCsv.qml</filename>):
Exportiert rekursiv alle Tags aller Dateien in eine CSV-Datei.
</para></listitem>
<listitem><para>
<guilabel>QML Console</guilabel>
(<filename>QmlConsole.qml</filename>):
Einfache Konsole, um die Funktionen von &kid3;'s QML API auszuprobieren.
</para></listitem>
</itemizedlist>
</para>

</sect1>

<sect1 id="qml-api">
<title>QML API</title>

<para>
Das API lässt sich leicht über die QML Console erkunden, welche als Beispiel
für ein Skript mit Benutzeroberfläche verfügbar ist.
</para>

<sect2 id="qml-kid3script">
<title>Kid3Script</title>

<para>
<classname>Kid3Script</classname> ist eine normale QML-Komponente im
Plugin-Verzeichnis. Man kann ebenso gut andere QML-Komponenten als Basis
brauchen. Die Verwendung von <classname>Kid3Script</classname> sorgt dafür,
dass sich eine Skript-Funktion einfach im <function>onRun</function> Signal
Handler aufrufen lässt. Falls das Skript keine weitere QML Komponenten
verwendet, bleibt es auch unabhängig von der QtQuick-Version, kann also sowohl
mit Qt 4 also auch mit Qt 5 verwendet werden. Darüber hinaus werden noch
einige Funktionen geboten:

<programlisting>
onRun: Signal Handler, welcher beim Start des Skripts aufgerufen wird
tagv1, tagv2, tagv2v1: Konstanten für tag Parameter
script: Zugriff auf Skript-Funktionen
configs: Zugriff auf Konfigurations-Objekte
getArguments(): Liste mit Skript-Argumenten
isStandalone(): true wenn Skript nicht aus Kid3 heraus gestartet wird
setTimeout(callback, delay): Startet callback nach delay ms
</programlisting>

</para>
</sect2>

<sect2 id="qml-script">
<title>Skript-Funktionen</title>

<para>
Da JavaScript und somit auch QML nur einen eingeschränkten Funktionsumfang für
Skripte mitbringt, stellt das <function>script</function> Objekt einige
Methoden zur Verfügung, welche den Funktionsumfang erweitern, unter anderem:
</para>

<programlisting>
script.properties(obj): Qt Eigenschaften des Objekts
script.writeFile(filePath, data): Schreibe in Datei, true wenn OK
script.readFile(filePath): Lese Daten von Datei
script.removeFile(filePath): Lösche Datei, true wenn OK
script.fileExists(filePath): true wenn Datei existiert
script.renameFile(oldName, newName): Datei umbenennen, true wenn OK
script.tempPath(): Verzeichnis temporärer Dateien
script.listDir(path, [nameFilters], [classify]): Liste der Verzeichniseinträge
script.system(program, [args], [msecs]): Systemkommando synchron ausführen,
  [exit code, standard output, standard error] wenn kein Timeout
script.getEnv(varName): Wert einer Umgebungsvariablen
script.setEnv(varName, value): Setze Wert einer Umgebungsvariablen
script.getQtVersion(): Qt Version, z.B. "5.4.1"
script.getDataMd5(data): MD5 Hash (hex) der Daten
script.getDataSize(data): Anzahl Datenbytes
script.dataToImage(data, [format]): Erzeuge Bild aus Daten
script.dataFromImage(img, [format]): Daten aus einem Bild
script.loadImage(filePath): Lade Bild aus einer Datei
script.saveImage(img, filePath, [format]): Speichere Bild in Datei, true wenn OK
script.imageProperties(img): Eigenschaften eines Bildes, enthält
  "width", "height", "depth" und "colorCount", leer wenn Bild ungültig
script.scaleImage(img, width, [height]): Liefert skaliertes Bild
script.selectFileName(caption, dir, filter, saveFile): Öffnet Dateidialog, um
eine Datei auszuwählen
</programlisting>

</sect2>

<sect2 id="qml-app">
<title>Applikations-Kontext</title>

<para>
Über QML ist ein großer Teil der &kid3; Funktionalität verfügbar. Das API ist
ähnlich wie bei <link linkend="dbus-api">D-Bus</link>. Für Details wird auf
die dortige Beschreibung verwiesen.
</para>

<programlisting>
app.openDirectory(path): Verzeichnis öffnen
app.saveDirectory(): Speichern
app.revertFileModifications(): Zuletzt gespeicherte Fassung
app.importTags(tag, path, fmtIdx): Datei importieren
app.downloadImage(url, allFilesInDir): Bild herunterladen
app.exportTags(tag, path, fmtIdx): Datei exportieren
app.writePlaylist(): Stückliste erstellen
app.selectAllFiles(): Alles auswählen
app.deselectAllFiles(): Gesamte Auswahl aufheben
app.firstFile([select]): Erste Datei
app.nextFile([select]): Nächste Datei
app.previousFile([select]): Vorangehende Datei
app.selectCurrentFile([select]): Aktuelle Datei auswählen
app.requestExpandFileList(): Alle ausklappen
app.applyFilenameFormat(): Dateinamenformat anwenden
app.applyTagFormat(): Tag-Format anwenden
app.applyTextEncoding(): Textkodierung anwenden
app.numberTracks(nr, total, tag, [options]): Tracks nummerieren
app.applyFilter(expr): Filter
app.convertToId3v23(): ID3v2.4 nach ID3v2.3 konvertieren
app.convertToId3v24(): ID3v2.3 nach ID3v2.4 konvertieren
app.getFilenameFromTags(tag): Dateiname von Tag
app.getTagsFromFilename(tag): Tag von Dateiname
app.getAllFrames(tag): Objekt mit allen Elementen
app.getFrame(tag, name): Hole Element
app.setFrame(tag, name, value): Setze Element
app.getPictureData(): Daten aus Bild-Element
app.setPictureData(data): Setze Daten in Bild-Element
app.copyToOtherTag(tag): Tag zu anderem Tag
app.copyTags(tag): Kopieren
app.pasteTags(tag): Einfügen
app.removeTags(tag): Entfernen
app.playAudio(): Wiedergabe
app.readConfig(): Konfiguration lesen
app.applyChangedConfiguration(): Konfiguration anwenden
app.dirName: Verzeichnisname
app.selectionInfo.fileName: Dateiname
app.selectionInfo.filePath: Absoluter Dateiname
app.selectionInfo.detailInfo: Format Details
app.selectionInfo.tagFormatV1: Tag 1 Format
app.selectionInfo.tagFormatV2: Tag 2 Format
app.selectionInfo.formatString(tag, format): Ersetze Format-Codes
</programlisting>

<para>
Für asynchrone Operationen können Callbacks mit Signalen verbunden werden.
</para>

<programlisting>
function automaticImport(profile) {
  function onAutomaticImportFinished() {
    app.batchImporter.finished.disconnect(onAutomaticImportFinished)
  }
  app.batchImporter.finished.connect(onAutomaticImportFinished)
  app.batchImport(profile, tagv2)
}

function renameDirectory(format) {
  function onRenameActionsScheduled() {
    app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
    app.performRenameActions()
  }
  app.renameActionsScheduled.connect(onRenameActionsScheduled)
  app.renameDirectory(tagv2v1, format, false)
}
</programlisting>

</sect2>

<sect2 id="qml-configs">
<title>Konfigurations-Objekte</title>

<para>
Die einzelnen Konfigurationen sind über Methoden von
<function>configs</function> verfügbar. Ihre Eigenschafen können in der QML
Console aufgelistet werden.

<screen width="80">
script.properties(configs.networkConfig())
</screen>

Eigenschaften können gesetzt werden:
<screen width="80">
configs.networkConfig().useProxy = false
</screen>
</para>

<programlisting>
configs.batchImportConfig()
configs.exportConfig()
configs.fileConfig()
configs.filenameFormatConfig()
configs.filterConfig()
configs.findReplaceConfig()
configs.guiConfig()
configs.importConfig()
configs.mainWindowConfig()
configs.networkConfig()
configs.numberTracksConfig()
configs.playlistConfig()
configs.renDirConfig()
configs.tagConfig()
configs.tagFormatConfig()
configs.userActionsConfig()
</programlisting>

</sect2>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: nxml
End:
-->
