ID3v2 tags, the metadata at the start of MP3 and other audio files.

It reads ID3v2.2, 2.3 and 2.4 as id3.org specifies them, along with the
chapters of the Chapter Frame Addendum, and writes 2.3 and 2.4. A tag is
a map of its header fields and its :frames. The frames namespace lists
the fields of each kind of frame.

Reading is strict. Each accommodation for a tag that breaks the spec is
a quirk with an id, and the diagnostics namespace lists them all. The
report of a reading names each quirk that applied. To turn quirks off,
name them in the :except option.

Chapters, as the ID3v2 Chapter Frame Addendum defines them: CHAP and
CTOC frames, and the order that a table of contents puts chapters in.

A CHAP frame is a chapter, a map of these fields:

- :element-id, its id in the tag
- :start-time and :end-time, in milliseconds
- :start-offset and :end-offset, the byte offsets in the file where it
  starts and ends, if it gives them
- :frames, the frames inside it, such as its title in a TIT2 frame

A CTOC frame is a table of contents: a map of its :element-id, the
element ids of its :children, its :frames and two flags. It's
:top-level? when it's the root of the tables, and :ordered? when its
children are in order.

A CHAP or CTOC frame inside another one keeps its content as bytes, as
frames of unknown kinds do, so nesting can't go deeper than one level.
To write chapters, put the table of contents that toc makes for them
first.

Every diagnostic that reading an ID3v2 tag can report, by id, with its
level and meaning.

A diagnostic is a map of an :id, a :level and a :message, plus details
such as the id of the :frame. The ids are part of the API, since apps
match on them. An app with a catalogue of its own can add this one to
it.

Most diagnostics are quirks: accommodations for tags that break the
spec. A reading applies every quirk that its :except option doesn't
name.

a text frame     :encoding and :text, and :values when it holds more
                 than one string
TXXX             :encoding, :description and :value
a URL frame      :url
WXXX             :encoding, :description and :url
COMM, USLT       :encoding, :language, :description and :text
APIC             :encoding, :mime-type, :picture-type, :description
                 and :data, or :url when the picture is a link
PIC              the same, with an :image-format such as JPG in place
                 of the MIME type
any other frame  :data, its content

The frames of an ID3v2 tag: their headers, and the layout of each kind
of frame.

A frame is a map of its :id and the fields of its kind:

    a text frame     :encoding and :text, and :values when it holds more
                     than one string
    TXXX             :encoding, :description and :value
    a URL frame      :url
    WXXX             :encoding, :description and :url
    COMM, USLT       :encoding, :language, :description and :text
    APIC             :encoding, :mime-type, :picture-type, :description
                     and :data, or :url when the picture is a link
    PIC              the same, with an :image-format such as JPG in place
                     of the MIME type
    any other frame  :data, its content

The three-letter ids of ID3v2.2, such as TT2 and COM, have the same
fields. A frame can also have :flags, the set of status flags that are
set, and :group, its group id.

A kind is a map of two functions. Its :read takes a reading context and
the content of a frame, and returns the frame's fields. Its :write does
the reverse: it takes a context and the frame, and returns the content.
A writing context holds the :version and the :kinds. The kinds table
holds the kinds by frame id, and the chapters namespace adds CHAP and
CTOC.

The text in ID3v2 frames: its four encodings, and strings that end in a
terminator.

A frame with text names its encoding in its first byte. ID3v2.4 has four
encodings: ISO-8859-1, UTF-16 with a byte order mark, UTF-16BE and
UTF-8. ID3v2.3 has only the first two. A string ends at a terminator,
which is a zero byte, or two for UTF-16, or else at the end of the frame.

The functions that read a frame take a reading context from
diagnostics/context, for the quirks of text that breaks the spec. The
functions that write one throw for text that the frame can't hold.