commenting/cleanup

README.md

@@ -1,8 +1,9 @@
 Copyright (c) 2013, Mark VandenBrink. All rights reserved.
 
-A pure Lisp implementation for reading MPEG-4 audio and MPEG-3 audio tags.
-
-Make your life simple---install quicklisp to get all the dependencies loaded!
+A pure Lisp implementation for reading MPEG-4 audio and MPEG-3 audio tags and audio information.
 
+Mostly complete.
 
+Most definitely, NOT portable.  Heavily dependent on Clozure CCL.
 
+Make your life simple---install quicklisp to get all the dependencies loaded!

audio-streams.lisp

@@ -9,21 +9,30 @@
 (deftype octet () '(unsigned-byte 8))
 (defmacro make-octets (len) `(make-array ,len :element-type 'octet))
 
+;;;
+;;; A simple stream interface for parsing audio files.  Currently, we have two basic stream types:
+;;; file-based and in-memory based, both of which implement the stream protocol of read, seek, etc.
+;;;
 (defclass base-stream ()
-  ((stream :accessor stream)))
+  ((stream :accessor stream))
+  (:documentation "Base class for audio-stream implementation"))
 
 (defclass base-file-stream (base-stream)
-  ((stream-filename :accessor stream-filename)))
+  ((stream-filename :accessor stream-filename))
+  (:documentation "File-based audio stream"))
 
 (defclass mp3-file-stream (base-file-stream)
-  ((id3-header  :accessor id3-header)
-   (audio-info   :accessor audio-info :initform nil)))
+  ((id3-header :accessor id3-header :initform nil :documentation "holds all the ID3 info")
+   (audio-info :accessor audio-info :initform nil :documentation "holds the bit-rate, etc info"))
+  (:documentation "Stream for parsing MP3 files"))
 
 (defclass mp4-file-stream (base-file-stream)
-  ((mp4-atoms  :accessor mp4-atoms :initform nil)
-   (audio-info :accessor audio-info :initform nil)))
+  ((mp4-atoms  :accessor mp4-atoms  :initform nil :documentation "holds tree of parsed MP4 atoms/boxes")
+   (audio-info :accessor audio-info :initform nil :documentation "holds the bit-rate, etc info"))
+  (:documentation "Stream for parsing MP4A files"))
 
 (defun make-file-stream (class-name filename &key (read-only t))
+  "Convenience function for creating a file stream."
   (let ((new-stream (make-instance (find-class class-name))))
 	(setf (stream new-stream) (if read-only
 								  (open filename :direction :input :element-type 'octet)
@@ -31,27 +40,34 @@
 	(setf (stream-filename new-stream) filename)
 	new-stream))
 
+;;;   (:documentation "In-memory stream")))
 (defclass base-mem-stream (base-stream) ())
 
 (defun make-mem-stream (vector)
+  "Convenience function to turn a vector into a stream."
   (let ((new-stream (make-instance 'base-mem-stream)))
 	(setf (stream new-stream) (ccl:make-vector-input-stream vector))
 	new-stream))
 
 (defmethod stream-close ((in-stream base-file-stream))
+  "Close the underlying file."
   (with-slots (stream) in-stream
 	(when stream
 	  (close stream)
 	  (setf stream nil))))
 
 (defmethod stream-close ((in-stream base-mem-stream))
+  "'Close' a memory stream by setting it to nil"
   (with-slots (stream) in-stream
 	(setf stream nil)))
 
 (defmethod stream-size ((in-stream base-stream))
+  "Returns the length of the underlying stream"
   (ccl::stream-length (stream in-stream)))
 
+
 (defmethod stream-seek ((in-stream base-stream) offset from)
+  "C-like stream positioner.  Takes an offset and a location (one of :start, :end, :current)."
   (with-slots (stream) in-stream
 	(ecase from
 	  (:start (ccl::stream-position stream offset))
@@ -60,65 +76,51 @@
 					(ccl::stream-position stream (+ (ccl::stream-position stream) offset))))
 	  (:end (ccl::stream-position stream (- (ccl::stream-length stream) offset))))))
 
+(defmethod stream-pos ((in-stream base-stream))
+  "Short hand for getting current stream read position"
+  (stream-seek in-stream 0 :current))
+
 (defun stream-read-octets (instream bytes &key (bits-per-byte 8))
+  "Used to slurp in octets for the stream-read-* methods"
   (loop with value = 0
 		for low-bit downfrom (* bits-per-byte (1- bytes)) to 0 by bits-per-byte do
 		  (setf (ldb (byte bits-per-byte low-bit) value) (read-byte instream))
 		finally (return value)))
 
 (defmethod stream-read-u8 ((in-stream base-stream) &key (bits-per-byte 8))
-  "read 1 byte from file"
+  "Read 1 byte from file"
   (with-slots (stream) in-stream
 	(stream-read-octets stream 1 :bits-per-byte bits-per-byte)))
 
 (defmethod stream-read-u16 ((in-stream base-stream) &key (bits-per-byte 8))
-  "read 2 bytes from file"
+  "Read 2 bytes from file"
   (with-slots (stream) in-stream
 	(stream-read-octets stream 2 :bits-per-byte bits-per-byte)))
 
 (defmethod stream-read-u24 ((in-stream base-stream) &key (bits-per-byte 8))
-  "read 3 bytes from file"
+  "Read 3 bytes from file"
   (with-slots (stream) in-stream
 	(stream-read-octets stream 3 :bits-per-byte bits-per-byte)))
 
 (defmethod stream-read-u32 ((in-stream base-stream) &key (bits-per-byte 8))
-  "read 4 bytes from file"
+  "Read 4 bytes from file"
   (with-slots (stream) in-stream
 	(stream-read-octets stream 4 :bits-per-byte bits-per-byte)))
 
 (defmethod stream-read-u64 ((in-stream base-stream) &key (bits-per-byte 8))
-  "read 8 bytes from file"
+  "Read 8 bytes from file"
   (with-slots (stream) in-stream
 	(stream-read-octets stream 8 :bits-per-byte bits-per-byte)))
 
-;; (defmethod stream-read-string ((stream base-stream) &key size (terminators nil))
-;;   "Read normal string from stream. If size is provided, read exactly that many octets.
-;; If terminators is supplied, it is a list of characters that can terminate a string (and hence stop read)"
-;;   (with-output-to-string (s)
-;; 	(with-slots (stream) stream
-;; 	  (let ((terminated nil)
-;; 			(count 0)
-;; 			(byte))
-;; 		(loop
-;; 		  (when (if size (= count size) terminated) (return))
-;; 		  (setf byte (read-byte stream))
-;; 		  (incf count)
-;; 		  (when (member byte terminators :test #'=)
-;; 			(setf terminated t))
-;; 		  (when (not terminated)
-;; 			(write-char (code-char byte) s)))))))
-
 (defmethod stream-read-sequence ((stream base-stream) size &key (bits-per-byte 8))
   "Read SIZE octets from input-file in BIT-PER-BYTE sizes"
   (log5:with-context "stream-read-sequence"
 	(ecase bits-per-byte
 	  (8
-	   ;(log-stream "reading ~:d bytes as 8-bit sequence" size)
 	   (let ((octets (make-octets size)))
 		 (read-sequence octets (slot-value stream 'stream))
 		 octets))
 	  (7
-	   ;(log-stream "reading ~:d bytes as 7-bit sequence" size)
 	   (let* ((last-byte-was-FF nil)
 			  (byte nil)
 			  (octets (ccl:with-output-to-vector (out)
@@ -129,23 +131,21 @@
 								  (write-byte byte out))
 							  (write-byte byte out))
 						  (setf last-byte-was-FF (= byte #xFF))))))
-		 ;(log-stream "file pos is now: ~:d" (stream-seek stream 0 :current))
-		 ;(log-stream "~a" (utils:printable-array octets))
 		 octets)))))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; STRINGS ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-;;
-;; decode octets as an iso-8859-1 string (encoding == 0)
+;;;
+;;; Decode octets as an iso-8859-1 string (encoding == 0)
 (defun stream-decode-iso-string (octets &key (start 0) (end nil))
   (ccl:decode-string-from-octets octets :start start :end end :external-format :iso-8859-1))
 
-;;
-;; decode octets as a ucs string (encoding == 1)
-;; XXX: Coded this way because I can't seem to get a simple :external-format :ucs-2 to work correctly
-;; AND some taggers encode a UCS-2 empty string w/o a byte-order mark (i.e. null strings are
-;; sometimes encoded as #(00 00))
+;;;
+;;; XXX: Coded this way because I can't seem to get a simple :external-format :ucs-2 to work correctly
+;;; AND some taggers encode a UCS-2 empty string w/o a byte-order mark (i.e. null strings are
+;;; sometimes encoded as #(00 00))
 (defun stream-decode-ucs-string (octets &key (start 0) (end nil))
+  "Decode octets as a UCS string with a BOM (encoding == 1)"
 	(labels ((get-byte-order-mark (octets)
 			   (let ((retval 0))
 				 (setf (ldb (byte 8 0) retval) (aref octets 1))
@@ -166,62 +166,52 @@
 				 (#xfeff (ccl:decode-string-from-octets octets :start (+ 2 start) :end end :external-format :ucs-2be))
 				 (0      (make-string 0))))))))
 
-;;
-;; decode octets as a ucs-be string (encoding == 2)
 (defun stream-decode-ucs-be-string (octets &key (start 0) (end nil))
+  "Decode octets as a UCS-BE string (encoding == 2)"
   (ccl:decode-string-from-octets octets :start start :end end :external-format :ucs-2be))
 
-;;
-;; decode octets as a utf-8 string
 (defun stream-decode-utf-8-string (octets &key (start 0) (end nil))
+  "Decode octets as a utf-8 string"
   (ccl:decode-string-from-octets octets :start start :end end :external-format :utf-8))
 
-;;
-;; decode octets depending on encoding
 (defun stream-decode-string (octets &key (start 0) (end nil) (encoding 0))
+  "Decode octets depending on encoding"
   (ecase encoding
-	(0 (stream-decode-iso-string octets :start start :end end))
-	(1 (stream-decode-ucs-string octets :start start :end end))
+	(0 (stream-decode-iso-string octets    :start start :end end))
+	(1 (stream-decode-ucs-string octets    :start start :end end))
 	(2 (stream-decode-ucs-be-string octets :start start :end end))
-	(3 (stream-decode-utf-8-string octets :start start :end end))))
+	(3 (stream-decode-utf-8-string octets  :start start :end end))))
 
-;;
-;; read an iso-8859-1 string of length 'len' (encoding = 0)
 (defmethod stream-read-iso-string-with-len ((instream base-stream) len)
+  "Read an iso-8859-1 string of length 'len' (encoding = 0)"
   (let ((octets (stream-read-sequence instream len)))
 	(stream-decode-iso-string octets)))
 
-;;
-;; read an ucs-2 string of length 'len' (encoding = 1)
 (defmethod stream-read-ucs-string-with-len ((instream base-stream) len)
+  "Read an ucs-2 string of length 'len' (encoding = 1)"
   (let ((octets (stream-read-sequence instream len)))
 	  (stream-decode-ucs-string octets)))
 
-;;
-;; read an ucs-2-be string of length 'len' (encoding = 2)
 (defmethod stream-read-ucs-be-string-with-len ((instream base-stream) len)
+  "Read an ucs-2-be string of length 'len' (encoding = 2)"
   (let ((octets (stream-read-sequence instream len)))
 	(stream-decode-ucs-be-string octets)))
 
-;;
-;; read an utf-8 string of length 'len' (encoding = 3)
 (defmethod stream-read-utf-8-string-with-len ((instream base-stream) len)
+  "Read an utf-8 string of length 'len' (encoding = 3)"
   (let ((octets (stream-read-sequence instream len)))
 	(stream-decode-utf-8-string octets)))
 
-;;
-;; Read in a string of a given encoding of length 'len'
 (defmethod stream-read-string-with-len ((instream base-stream) len &key (encoding 0))
-  ;(format t "s-wth-len: ~a, ~d, ~d~%" instream len encoding)
+  "Read in a string of a given encoding of length 'len'"
   (ecase encoding
 	(0 (stream-read-iso-string-with-len instream len))
 	(1 (stream-read-ucs-string-with-len instream len))
 	(2 (stream-read-ucs-be-string-with-len instream len))
 	(3 (stream-read-utf-8-string-with-len instream len))))
 
-;;
-;; Read in a null terminated iso-8859-1 string
 (defmethod stream-read-iso-string ((instream base-stream))
+  "Read in a null terminated iso-8859-1 string"
   (let ((octets (ccl:with-output-to-vector (out)
 				  (do ((b (stream-read-u8 instream) (stream-read-u8 instream)))
 					  (nil)
@@ -230,9 +220,8 @@
 					(write-byte b out)))))
 	(stream-decode-iso-string octets)))
 
-;;
-;; Read in a null terminated ucs string 
 (defmethod stream-read-ucs-string ((instream base-stream))
+  "Read in a null terminated UCS string."
   (let ((octets (ccl:with-output-to-vector (out)
 				  (do* ((b0 (stream-read-u8 instream)
 							(stream-read-u8 instream))
@@ -245,9 +234,8 @@
 					(write-byte b1 out)))))
 	(stream-decode-ucs-string octets)))
 
-;;
-;; Read in a null terminated ucs-be string
 (defmethod stream-read-ucs-be-string ((instream base-stream))
+  "Read in a null terminated UCS-BE string."
   (let ((octets (ccl:with-output-to-vector (out)
 				  (do* ((b0 (stream-read-u8 instream)
 							(stream-read-u8 instream))
@@ -260,9 +248,8 @@
 					(write-byte b1 out)))))
 	(stream-decode-ucs-be-string octets)))
 
-;;
-;; Read in a null terminated utf-8 string (encoding == 3)
 (defmethod stream-read-utf-8-string ((instream base-stream))
+  "Read in a null terminated utf-8 string (encoding == 3)"
   (let ((octets (ccl:with-output-to-vector (out)
 				  (do ((b (stream-read-u8 instream)
 						  (stream-read-u8 instream)))
@@ -272,17 +259,19 @@
 					(write-byte b out)))))
 	(stream-decode-utf-8-string octets)))
 
-;;
-;; Read in a null terminated string of a given encoding
 (defmethod stream-read-string ((instream base-stream) &key (encoding 0))
+  "Read in a null terminated string of a given encoding."
   (ecase encoding
-	(0 (stream-read-iso-string instream))
-	(1 (stream-read-ucs-string instream))
+	(0 (stream-read-iso-string    instream))
+	(1 (stream-read-ucs-string    instream))
 	(2 (stream-read-ucs-be-string instream))
-	(3 (stream-read-utf-8-string instream))))
+	(3 (stream-read-utf-8-string  instream))))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; FILES ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+(defvar *get-audio-info* t "controls whether the parsing functions also parse audio info like bit-rate, etc")
+
 (defun parse-mp4-file (filename &key (get-audio-info *get-audio-info*))
+  "Parse an MP4A file by reading it's ATOMS and decoding them."
   (let (stream)
 	(handler-case
 		(progn
@@ -296,9 +285,8 @@
 		(setf stream nil)))
 	stream))
 
-(defvar *get-audio-info* nil)
-
 (defun parse-mp3-file (filename &key (get-audio-info *get-audio-info*))
+  "Parse an MP3 file by reading it's FRAMES and decoding them."
   (let (stream)
 	  (handler-case
 		  (progn

id3-frame.lisp

@@ -72,7 +72,8 @@ and/or end (version 2.1)"
 	  (setf album    (upto-null (stream-read-string-with-len instream 30)))
 	  (setf year     (upto-null (stream-read-string-with-len instream 4)))
 	  (setf comment  (stream-read-string-with-len instream 30))
-	  ;; In V21, a comment can be split into comment and track#
+
+	  ;; In V21, a comment can be split into comment and track #
 	  ;; find the first #\Null then check to see if that index < 28.  If so, the check the last two bytes being
 	  ;; non-zero---if so, then track can be set to integer value of last two bytes
 	  (let ((trimmed-comment (upto-null comment))
@@ -92,7 +93,7 @@ and/or end (version 2.1)"
    (flags   :accessor flags   :initarg :flags   :initform 0)
    (padding :accessor padding :initarg :padding :initform 0)
    (crc	    :accessor crc     :initarg :crc     :initform nil))
-  (:documentation "class representing a V2.3/4 extended header"))
+  (:documentation "Class representing a V2.3/4 extended header"))
 
 (defmacro ext-header-crc-p    (flags) `(logbitp 14 ,flags))
 
@@ -105,11 +106,13 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 	(setf flags (stream-read-u16 instream))
 	(setf padding (stream-read-u32 instream))
 	(when (not (zerop flags))
+
 	  ;; at this point, we have to potentially read in other fields depending on flags.
 	  ;; for now, just error out...
-	  (assert (zerop flags) () "non-zero extended header flags = ~x, check validity"))))
-	;;(when (ext-header-crc-p flags)
-	;;  (setf crc (stream-read-u32 instream)))))
+	  (assert (zerop flags) () "non-zero extended header flags = ~x, check validity")
+	  ;;(when (ext-header-crc-p flags)
+	  ;;  (setf crc (stream-read-u32 instream)))))
+	  )))
 
 (defmethod vpprint ((me id3-ext-header) stream)
   (with-slots (size flags padding crc) me
@@ -180,7 +183,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 ;;; to read in that class (each defined class is assumed to have an INITIALIZE-INSTANCE method
 ;;; that reads in data to build class.
 ;;;
-;;; Each frame class assumes that the STREAM being passed in is sync-safe.
+;;; Each frame class assumes that the STREAM being passed has been made sync-safe.
 ;;;
 ;;; For any class we don't want to parse (eg, haven't gotten around to it yet, etc), we create
 ;;; a RAW-FRAME class that can be subclassed.  RAW-FRAME simply reads in the frame header, and then
@@ -189,7 +192,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 ;;;
 ;;; many ID3 tags are name/value pairs, with the name/value encoded in various ways
 ;;; this routine assumes that the "name" is always a string with a "normal" encoding (i.e. 0, 1, 2, or 3).
-;;; The "value", however, also accepts any negative number, which means read
+;;; The "value" field accepts "normal" encoding, but also accepts any negative number, which means read
 ;;; the bytes an raw octets.
 (defun get-name-value-pair (instream len name-encoding value-encoding)
   (log5:with-context  "get-name-value-pair"
@@ -287,8 +290,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
   (with-slots (octets) me
 	(format stream "frame-raw: ~a, ~a" (vpprint-frame-header me) (printable-array octets))))
 
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; V2.1 frames ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;; v22 frames I haven't written a class for yet
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; V2.2 frames ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (defclass frame-buf (frame-raw) ())
 (defclass frame-cnt (frame-raw) ())
 (defclass frame-cra (frame-raw) ())
@@ -312,15 +314,14 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 (defclass frame-wpb (frame-raw) ())
 (defclass frame-stc (frame-raw) ())
 
-;;; V22 User defined...   "WXX"
-;;; Text encoding     $xx
-;;; Description       <textstring> $00 (00)
-;;; URL               <textstring>
+;;; V22 User defined... "WXX"
+;;; Text encoding       $xx
+;;; Description         <textstring> $00 (00)
+;;; URL                 <textstring>
 ;;; Identical to TXX
 (defclass frame-wxx (frame-txx) ())
 
 
-
 ;; V22 COM frames
 ;; Comment                   "COM"
 ;; Text encoding             $xx
@@ -402,7 +403,8 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
   (log5:with-context "frame-text-info"
 	(with-slots (version flags len encoding info) me
 	  (let ((read-len len))
-		;; in version 4 frames, each frame may also have an unsync flag.  since we have unsynced already
+
+		;; In version 4 frames, each frame may also have an unsync flag.  since we have unsynced already
 		;; the only thing we need to do here is check for the optional DATALEN field.  If it is present
 		;; then it has the actual number of octets to read
 		(when (and (= version 4) (frame-24-unsynch-p flags))
@@ -412,7 +414,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 		(setf encoding (stream-read-u8 instream))
 		(setf info (stream-read-string-with-len instream (1- read-len) :encoding encoding)))
 
-	  ;; a null is ok, but according to the "spec", you're supposed to ignore anything after a 'Null'
+	  ;; A null is ok, but according to the "spec", you're supposed to ignore anything after a 'Null'
 	  (log-id3-frame "made text-info-frame: ~a" (vpprint me nil))
 	  (setf info (upto-null info))
 
@@ -459,7 +461,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 (defclass frame-txt (frame-text-info) ())
 (defclass frame-tye (frame-text-info) ())
 
-;; v22 User defined "TXX" frames
+;; V22 User defined "TXX" frames
 ;; Text encoding     $xx
 ;; Description       <textstring> $00 (00)
 ;; Value             <textstring>
@@ -503,7 +505,6 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 	(format stream "frame-ufi: ~a, name: <~a>, value: ~a" (vpprint-frame-header me) name (printable-array value))))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; V23/V24 frames ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;; v23/v24 frame I haven't written a class for yet
 (defclass frame-aenc (frame-raw) ())
 (defclass frame-aspi (frame-raw) ())
 (defclass frame-comr (frame-raw) ())
@@ -603,7 +604,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 	"During recording"
 	"During performance"
 	"Movie/video screen capture"
-	"A bright coloured fish"	; how do you know the fish is smart :)
+	"A bright coloured fish"	; how do you know the fish is intelligent? :)
 	"Illustration"
 	"Band/artist logotype"
 	"Publisher/Studio logotype"))
@@ -623,7 +624,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 ;; Picture data    <binary data>
 (defclass frame-apic (id3-frame)
   ((encoding :accessor encoding)
-   (mime     :accessor mime)<
+   (mime     :accessor mime)
    (type     :accessor type)
    (desc     :accessor desc)
    (data     :accessor data))
@@ -656,7 +657,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
    (lang	 :accessor lang)
    (desc     :accessor desc)
    (val		 :accessor val))
-  (:documentation "Comment frame"))
+  (:documentation "V23/4 Comment frame"))
 
 (defmethod initialize-instance :after ((me frame-comm) &key instream)
   (log5:with-context "frame-comm"
@@ -678,7 +679,7 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 ;;; Unsynchronized lyrics frames look very much like comment frames...
 (defclass frame-uslt (frame-comm) ())
 
-;;; v23/24 PCNT frames
+;;; V23/24 PCNT frames
 ;;; <Header for 'Play counter', ID: "PCNT">
 ;;; Counter         $xx xx xx xx (xx ...)
 (defclass frame-pcnt (id3-frame)
@@ -899,7 +900,6 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 						 (log-id3-frame "bottom of read-loop: pos = ~:d, size = ~:d" (stream-seek stream 0 :current) (stream-size stream))
 						 (push this-frame frames))
 					 (condition (c)
-					   ;; XXX need to 'handle' warnings here...
 					   (log-id3-frame "got condition ~a when making frame" c)
 					   (return-from read-loop (values nil (nreverse frames))))))
 
@@ -915,18 +915,19 @@ Note: extended headers are subject to unsynchronization, so make sure that INSTR
 
 	  (setf (id3-header mp3-file) (make-instance 'id3-header :instream mp3-file))
 	  (with-slots (size ext-header frames flags version) (id3-header mp3-file)
-		;; at this point, we switch from reading the file stream and create a memory stream
+
+		;; At this point, we switch from reading the file stream and create a memory stream
 		;; rationale: it may need to be unsysnc'ed and it helps prevent run-away reads with
 		;; mis-formed frames
 		(when (not (zerop size))
 		  (let ((mem-stream (make-mem-stream (stream-read-sequence mp3-file size
 																   :bits-per-byte (if (header-unsynchronized-p flags) 7 8)))))
 
-			;; must make extended header here since it is subject to unsynchronization.
+			;; Must make extended header here since it is subject to unsynchronization.
 			(when (header-extended-p flags)
 			  (setf ext-header (make-instance 'id3-extended-header :instream mem-stream)))
 
-			;; start reading frames from memory stream
+			;; Start reading frames from memory stream
 			(multiple-value-bind (_ok _frames) (read-loop version mem-stream)
 			  (if (not _ok)
 				  (warn-user "File ~a had errors finding mp3 frames. potentially missed frames!" (stream-filename mp3-file)))

iso-639-2.lisp

@@ -490,6 +490,7 @@
    :XXX "Not Used"))
 
 (defun get-iso-639-2-language (l)
+  "Convert an ISO-639-2 language tag into a readable language."
   (let* ((lang (getf *langs* (alexandria:make-keyword (string-upcase l)))))
 	(if lang lang "Bad ISO-639-2 language")))
 

mp3-tag.lisp

@@ -298,9 +298,6 @@
 	  (return-from lyrics (val (first frames)))))
   nil)
 
-;;;(defmethod purchased-date ((me mp3-file-stream)) "NIY")
-;;;(defmethod tool ((me mp3-file-stream)) "NIY")
-
 (defmethod writer ((me mp3-file-stream))
   (let ((frames (get-frames me '("TCM" "TCOM"))))
 	(when frames
@@ -364,10 +361,8 @@
 			(genre (genre me))
 			(groups (groups me))
 			(lyrics (lyrics me))
-			;;(purchased-date (purchased-date me))
 			(tempo (tempo me))
 			(title (title me))
-			;;(tool (tool me))
 			(track (track me))
 			(writer (writer me))
 			(year (year me)))
@@ -386,10 +381,8 @@
 		(when genre (format t "~4tgenre: ~a~%" genre))
 		(when groups (format t "~4tgroups: ~a~%" groups))
 		(when lyrics (format t "~4tlyrics: ~a~%" lyrics))
-		;;(when purchased-date (format t "~4tpurchased date: ~a~%" purchased-date))
 		(when tempo (format t "~4ttempo: ~a~%" tempo))
 		(when title (format t "~4ttitle: ~a~%" title))
-		;;(when tool (format t "~4ttool: ~a~%" tool))
 		(when track (format t "~4ttrack: ~a~%" track))
 		(when writer (format t "~4twriter: ~a~%" writer))
 		(when year (format t "~4tyear: ~a~%" year)))))

mp4-atom.lisp

@@ -362,25 +362,23 @@ Loop through this container and construct constituent atoms"
 	(setf flags    (stream-read-u24 mp4-file))
 	(assert (= 3 (stream-read-u8 mp4-file)) () "Expected a description tag of 3")
 	(let* ((len1 (read-descriptor-len mp4-file))
-		   (end-of-atom (+ (stream-seek mp4-file 0 :current) len1))
-		   (len2 0))
-	  (declare (ignore len2)) ; XXX for now...
+		   (end-of-atom (+ (stream-seek mp4-file 0 :current) len1)))
 	  (setf esid (stream-read-u16 mp4-file))
 	  (setf s-priority (stream-read-u8 mp4-file))
 	  ;; XXX should do some range checking here against LEN1...
 	  (assert (= 4 (stream-read-u8 mp4-file)) () "Expected tag type of 4")
-	  (setf len2 (read-descriptor-len mp4-file))
+	  (read-descriptor-len mp4-file) ; eat, but don't store descriptor header len
 	  (setf obj-id (stream-read-u8 mp4-file))
 	  (setf s-type (stream-read-u8 mp4-file))
 	  (setf buf-size (stream-read-u24 mp4-file))
 	  (setf max-bit-rate (stream-read-u32 mp4-file))
 	  (setf avg-bit-rate (stream-read-u32 mp4-file))
-	  ;; XXX should do checking here on LEN2 and/or read rest of atom,
+	  ;; XXX should do checking hereand/or read rest of atom,
 	  ;; but for now, we have what we want, so just seek to end of atom
 	  (stream-seek mp4-file end-of-atom :start))))
 
 (defclass atom-stsd (mp4-atom)
-  ((flags        :accessor flags)
+  ((flags       :accessor flags)
    (version     :accessor version)
    (num-entries :accessor num-entries)))
 

mp4-tag.lisp

@@ -13,9 +13,7 @@
 (defmethod encoder ((me mp4-file-stream))        (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-encoder+))
 (defmethod groups ((me mp4-file-stream))         (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-groups+))
 (defmethod lyrics ((me mp4-file-stream))         (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-lyrics+))
-;;;(defmethod purchased-date ((me mp4-file-stream)) (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-purchased-date+))
 (defmethod title ((me mp4-file-stream))          (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-title+))
-;;;(defmethod tool ((me mp4-file-stream))           (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-tool+))
 (defmethod writer ((me mp4-file-stream))         (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-writer+))
 (defmethod compilation ((me mp4-file-stream))    (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-compilation+))
 (defmethod disk  ((me mp4-file-stream))          (mp4-atom:tag-get-value (mp4-atoms me) mp4-atom:+itunes-disk+))
@@ -56,10 +54,8 @@
 			(genre (genre me))
 			(groups (groups me))
 			(lyrics (lyrics me))
-			;;(purchased-date (purchased-date me))
 			(tempo (tempo me))
 			(title (title me))
-			;;(tool (tool me))
 			(track (track me))
 			(writer (writer me))
 			(year (year me)))
@@ -78,10 +74,8 @@
 		(when genre (format t "~4tgenre: ~a~%" genre))
 		(when groups (format t "~4tgroups: ~a~%" groups))
 		(when lyrics (format t "~4tlyrics: ~a~%" lyrics))
-		;;(when purchased-date (format t "~4tpurchased date: ~a~%" purchased-date))
 		(when tempo (format t "~4ttempo: ~a~%" tempo))
 		(when title (format t "~4ttitle: ~a~%" title))
-		;;(when tool (format t "~4ttool: ~a~%" tool))
 		(when track (format t "~4ttrack: ~a~%" track))
 		(when writer (format t "~4twriter: ~a~%" writer))
 		(when year (format t "~4tyear: ~a~%" year)))))

taglib-tests.lisp

@@ -53,7 +53,7 @@
 								 (let ((file (mp4-test0 f)))
 								   (when file 
 									 (mp4-tag:show-tags file :raw raw)
-									 (mp4-atom::get-audio-info file)))))))
+									 (mp4-atom::get-mp4-audio-info file)))))))
 
 ;;;;;;;;;;;;;;;;;;;; MP3 Tests ;;;;;;;;;;;;;;;;;;;;
 (defun mp3-test0 (file)