dk.simongray.id3.frames — dk.simongray/id3-clj 0.1.0

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.

added-fields clj/s

The fields that frame flags add after the frame header, by version, in order, as pairs of the flag and the size of its field.

code clj/s

(code b p n)

The n bytes at p in b as ISO-8859-1 text, which is how frame ids and the languages of comments are written.

flag-bits clj/s

Where each flag is in the two flag bytes of a frame header, by version, as pairs of the byte and the bit.

id? clj/s

(id? version s)

Whether s is the id of a frame of version: three capitals or digits for ID3v2.2, four for 2.3 and 2.4.

image-signatures clj/s

The MIME type of each image format, with the bytes that its files start with, where nil stands for any byte.

kind clj/s

(kind kinds id)

The kind of the frame id: its entry in kinds, or else the kind of text or URL frames when id starts with T or W, or else other-frame.

kinds clj/s

The kinds of frames that have a layout of their own, by id, including the ids of ID3v2.2, which can be read but not written.

loose-type? clj/s

(loose-type? mime-type)

Whether the mime-type of a picture frame is loose, such as JPG or image/jpg, or missing.

number clj/s

(number b p n)

The big-endian number of the n bytes at p in b.

number-bytes clj/s

(number-bytes x n)

The n bytes of the whole number x, big-endian. It throws when x isn't a whole number that they can hold.

other-frame clj/s

The kind of a frame without a kind of its own, which keeps its content as it is.

picture-types clj/s

The name of each picture type of an APIC or PIC frame, by its number.

plausible-end? clj/s

(plausible-end? b version p end)

Whether a frame of version that ends at p in b is followed by something that can follow a frame before end:

• nothing
• the header of another frame
• padding, which is zeros up to the end of the tag, of which it checks the first kilobyte

read clj/s

(read ctx b start end)

The frames in b from start up to the padding or end, read in the context ctx.

The context holds the :version of the tag and the :kinds of frames. It skips a frame that is compressed or encrypted, and leaves out one whose content can't be parsed. A header that can't be parsed ends the frames. The report notes each of these, except a header that was cut off in a tag that is :truncated?.

read-comment clj/s

(read-comment ctx b)

The fields of the COMM or USLT frame whose content is b, read in the context ctx: its encoding, a language, a description and a text.

read-other clj/s

(read-other _ b)

The fields of a frame of a kind without a reader, whose content is b: the content as it is.

read-pic clj/s

(read-pic ctx b)

The fields of the PIC frame of ID3v2.2 whose content is b, read in the context ctx: its encoding, an image format, a picture type, a description, and the image or a link to it.

read-picture clj/s

(read-picture ctx b)

The fields of the APIC frame whose content is b, read in the context ctx: its encoding, a MIME type, a picture type, a description, and the image or a link to it.

read-text clj/s

(read-text ctx b)

The fields of the text frame whose content is b, read in the context ctx: its encoding and one string, or more in ID3v2.4.

read-url clj/s

(read-url ctx b)

The fields of the URL frame whose content is b, read in the context ctx: its URL.

read-user-text clj/s

(read-user-text ctx b)

The fields of the TXXX frame whose content is b, read in the context ctx: its encoding, a description and a value.

read-user-url clj/s

(read-user-url ctx b)

The fields of the WXXX frame whose content is b, read in the context ctx: its encoding, a description and a URL.

resync clj/s

(resync b)

The bytes b with unsynchronisation undone, i.e. without the zero byte after each 0xFF.

sniff-image clj/s

(sniff-image b)

The MIME type of the image in b when it starts like a JPEG, PNG, GIF or WebP file, or else nil.

status-flags clj/s

The flags that a frame keeps in its :flags. They say what to do with the frame, not how to parse it.

syncsafe clj/s

(syncsafe b p)

The syncsafe integer in the four bytes at p in b, or nil when one of them has its top bit set, which a syncsafe integer never has.

syncsafe-bytes clj/s

(syncsafe-bytes x)

The four bytes of x as a syncsafe integer. It throws when x doesn't fit in its 28 bits.

text-frame clj/s

The kind of the text frames, whose ids start with T.

u8 clj/s

(u8 b p)

The byte at p in b, from 0 to 255. It throws when p is past the end of b, so that a frame too short for its kind fails to parse.

url-frame clj/s

The kind of the URL frames, whose ids start with W.

write clj/s

(write ctx frames)

The bytes of the frames, one after another, written in the context ctx, which holds the :version of the tag and the :kinds of frames.

It throws when a frame can't be written, with the id of the frame as the :frame of the exception's data.

write-comment clj/s

(write-comment ctx
               {:keys [encoding language description text]
                :or {language "und" description ""}
                :as frame})

The content of the COMM or USLT frame frame, written in the context ctx. Without a :language, it writes und, the code for a language that isn't known.

write-other clj/s

(write-other _ {:keys [data] :as frame})

The content of the frame frame, of a kind without a writer, written in the context ctx: its :data as it is.

write-picture clj/s

(write-picture ctx
               {:keys [encoding mime-type picture-type description data url]
                :or {mime-type "" picture-type 0 description ""}
                :as frame})

The content of the APIC frame frame, written in the context ctx: a link when it has a :url, or else its :data.

Without a :picture-type, it writes 0, other. Without a :mime-type, it writes an empty one, which ID3 takes as image/.

write-text clj/s

(write-text ctx {:keys [encoding text values] :as frame})

The content of the text frame frame, written in the context ctx: its :values, or else its :text.

ID3v2.3 has room for only one string, so there it joins the values with slashes, as ID3v2.3 does for the people in TPE1 and the like.

write-url clj/s

(write-url _ {:keys [url] :as frame})

The content of the URL frame frame, written in the context ctx.

write-user-text clj/s

(write-user-text
  ctx
  {:keys [encoding description value] :or {description ""} :as frame})

The content of the TXXX frame frame, written in the context ctx.

write-user-url clj/s

(write-user-url
  ctx
  {:keys [encoding description url] :or {description ""} :as frame})

The content of the WXXX frame frame, written in the context ctx.