%Copyright (C) 2007-2015  Brian Langenberger
%This work is licensed under the
%Creative Commons Attribution-Share Alike 3.0 United States License.
%To view a copy of this license, visit
%http://creativecommons.org/licenses/by-sa/3.0/us/ or send a letter to
%Creative Commons,
%171 Second Street, Suite 300,
%San Francisco, California, 94105, USA.

\chapter{APEv2 Tags}
\label{apev2}
APEv2 tags are a format-agnostic way of attaching metadata to audio files.
It is used by WavPack, Musepack, Monkey's Audio and others.
In most cases APEv2 tags are attached to the end of the file,
but it is possible to attach them to the beginning.

\begin{figure}[h]
  \includegraphics{figures/apev2/tag.pdf}
\end{figure}
\par
\noindent
When attached to the end of a file, the footer is required
and the header is optional.
When attached to the beginning of a file, the header is required
and the footer is optional.
Because the header and footer are fixed sizes,
this placement allows one to locate them the file
unambiguously.

All fields within an APEv2 tag are little-endian.
All items within an APEv2 tag should be sorted
by ascending size.

\clearpage

\section{APEv2 Header / Footer}
\begin{figure}[h]
  \includegraphics{figures/apev2/header.pdf}
\end{figure}
\par
\noindent
\VAR{tag size} is the size of the APEv2 tag including
any header, but \textit{not} including the footer.
\VAR{item count} is the number of APEv2 tag items.
\VAR{read only} indicates the APEv2 tag is read-only.
\VAR{item encoding} is not used by the header or footer.
\VAR{is header} indicates this is the header.
\VAR{contains no footer} indicates the tag contains no footer.
\VAR{contains a header} indicates the tag contains a header.

\subsection{APEv2 Footer Example}
\begin{figure}[h]
  \includegraphics{figures/apev2/footer-example.pdf}
\end{figure}
\begin{figure}[h]
  \includegraphics{figures/apev2/footer-flags.pdf}
  \caption{footer flags}
\end{figure}

\clearpage

\begin{tabular}{rl}
preamble : & \texttt{"APETAGEX"} \\
version : & \texttt{2000} \\
tag size : & \texttt{99} bytes \\
item count : & \texttt{3} \\
read only : & \texttt{0} \\
item encoding : & \texttt{0} (unused) \\
is header : & \texttt{0} \\
contains no footer : & \texttt{0} \\
contains a header : & \texttt{1} \\
\end{tabular}
\par
\noindent
Because the tag size is 99 bytes, the full size of the tag
is 131 bytes (99 + 32 bytes for footer).
And, because \VAR{contains a header} is set,
the first 32 bytes of the tag contain an identically-formatted header.

\begin{figure}[h]
  \includegraphics{figures/apev2/full-example.pdf}
  \caption{Complete APEv2 Tag}
\end{figure}
\begin{figure}[h]
  \includegraphics{figures/apev2/header-flags.pdf}
  \caption{header flags}
\end{figure}

\clearpage

\section{APEv2 Item}
\begin{figure}[h]
  \includegraphics{figures/apev2/item.pdf}
\end{figure}
\par
\noindent
\VAR{read only} indicates the item is read-only.
\VAR{item encoding} is \texttt{0} for UTF-8,
\texttt{1} for binary information,
\texttt{2} for a UTF-8-encoded external URL
and \texttt{3} is undefined.
\VAR{is header}, \VAR{contains no footer} and \VAR{contains a header}
are unused by tag items.
\VAR{item key} is a NULL-terminated ASCII string
with values from \texttt{0x20} to \texttt{0x7E}, inclusive.
\begin{table}[h]
{\relsize{-1}
\begin{tabular}{rl}
item key & meaning \\
\hline
\texttt{Title} & music piece title \\
\texttt{Subtitle} & title when \texttt{Title} contains the work or additional sub title \\
\texttt{Artist} & performing artist \\
\texttt{Album} & album name \\
\texttt{Publisher} & record label or publisher \\
\texttt{Conductor} & conductor \\
\texttt{Track} & track number or track number/total tracks number \\
\texttt{Composer} & name of the original composer \\
\texttt{Comment} & user comment(s) \\
\texttt{Copyright} & copyright holder \\
\texttt{EAN} / \texttt{UPC} & EAN-13/UPC-A bar code identifier \\
\texttt{ISBN} & ISBN number with check digit \\
\texttt{Catalog} & catalog number \\
\texttt{Year} & release date \\
\texttt{Record Date} & record date \\
\texttt{Genre} & genre \\
\texttt{Media} & source media number/total media number \\
\texttt{ISRC} & International Standard Recording Number \\
\texttt{Dummy} & placeholder binary data \\
\texttt{Cover Art (Front)} & front cover binary data \\
\texttt{Cover Art (Back)} & back cover binary data \\
\texttt{Cuesheet} & cuesheet binary data \\
\end{tabular}
}
\end{table}

\clearpage

\subsection{APEv2 Item Examples}
\begin{figure}[h]
  \includegraphics{figures/apev2/item-example1.pdf}
\end{figure}
\par
\noindent
\begin{tabular}{rl}
item key : & \texttt{"Year"} \\
item value : & \texttt{"2012"} \\
\end{tabular}
\begin{figure}[h]
  \includegraphics{figures/apev2/item-example2.pdf}
\end{figure}
\par
\noindent
\begin{tabular}{rl}
item key : & \texttt{"Artist"} \\
item value : & \texttt{"Artist Name"} \\
\end{tabular}
\begin{figure}[h]
  \includegraphics{figures/apev2/item-example3.pdf}
\end{figure}
\par
\noindent
\begin{tabular}{rl}
  item key : & \texttt{"Title"} \\
  item value : & \texttt{"Track Name"} \\
\end{tabular}
