feat: Enhance ID3 Support: Implement APIC Functionality

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Unit tests for id3 feature helper functions [#74](https://github.com/streaming-video-technology-alliance/common-media-library/pull/74)
+- Id3 APIC frame decode functionality, and it's respective unit tests [#77](https://github.com/streaming-video-technology-alliance/common-media-library/issues/77)
 
 
 ## [0.6.2] - 2023-01-18

lib/src/id3.ts

@@ -14,3 +14,4 @@ export { getId3Data } from './id3/getId3Data.js';
 export { getId3Frames } from './id3/getId3Frames.js';
 export { getId3Timestamp } from './id3/getId3Timestamp.js';
 export { isId3TimestampFrame } from './id3/isId3TimestampFrame.js';
+export { decodeId3TextFrame } from './id3/util/decodeId3TextFrame.js';

lib/src/id3/getId3Frames.ts

@@ -26,6 +26,11 @@ export function getId3Frames(id3Data: Uint8Array): Id3Frame[] {
 
 	while (isId3Header(id3Data, offset)) {
 		const size = readId3Size(id3Data, offset + 6);
+
+		if ((id3Data[offset + 5] >> 6) & 1) {
+			// skip extended header
+			offset += HEADER_FOOTER_SIZE;
+		}
 		// skip past ID3 header
 		offset += HEADER_FOOTER_SIZE;
 		const end = offset + size;
@@ -38,7 +43,7 @@ export function getId3Frames(id3Data: Uint8Array): Id3Frame[] {
 			}
 
 			// skip frame header and frame data
-			offset += frameData.size + 10;
+			offset += frameData.size + HEADER_FOOTER_SIZE;
 		}
 
 		if (isId3Footer(id3Data, offset)) {

lib/src/id3/util/decodeId3Frame.ts

@@ -3,6 +3,7 @@ import { RawId3Frame } from './RawFrame.js';
 import { decodeId3PrivFrame } from './decodeId3PrivFrame.js';
 import { decodeId3TextFrame } from './decodeId3TextFrame.js';
 import { decodeId3UrlFrame } from './decodeId3UrlFrame.js';
+import { decodeId3ImageFrame } from './decodeId3ImageFrame.js';
 
 /**
  * Decode an ID3 frame.
@@ -23,5 +24,9 @@ export function decodeId3Frame(frame: RawId3Frame): Id3Frame | undefined {
 		return decodeId3UrlFrame(frame);
 	}
 
+	else if (frame.type === 'APIC') {
+		return decodeId3ImageFrame(frame);
+	}
+
 	return decodeId3TextFrame(frame);
 }

lib/src/id3/util/decodeId3ImageFrame.ts

@@ -0,0 +1,168 @@
+import { DecodedId3Frame } from '../DecodedId3Frame.js';
+import { RawId3Frame } from './RawFrame.js';
+import { toUint8 } from './utf8.js';
+import { BufferSource } from 'stream/web';
+
+type TypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | Uint8ClampedArray;
+
+interface MetadataFrame {
+	key: string;
+	description: string;
+	data: string | ArrayBuffer;
+	mimeType: string | null;
+	pictureType: number | null;
+}
+
+export function decodeId3ImageFrame(
+	frame: RawId3Frame
+): DecodedId3Frame<string | ArrayBuffer> | undefined {
+	const metadataFrame: MetadataFrame = {
+		key: frame.type,
+		description: '',
+		data: '',
+		mimeType: null,
+		pictureType: null,
+	};
+
+	const utf8Encoding = 0x03;
+
+	if (frame.size < 2) {
+		return undefined;
+	}
+	if (frame.data[0] !== utf8Encoding) {
+		console.log('Ignore frame with unrecognized character ' + 'encoding');
+		return undefined;
+	}
+
+	const mimeTypeEndIndex = frame.data.subarray(1).indexOf(0);
+	if (mimeTypeEndIndex === -1) {
+		return undefined;
+	}
+	const mimeType = fromUTF8(toUint8(frame.data, 1, mimeTypeEndIndex));
+	const pictureType = frame.data[2 + mimeTypeEndIndex];
+	const descriptionEndIndex = frame.data
+		.subarray(3 + mimeTypeEndIndex)
+		.indexOf(0);
+	if (descriptionEndIndex === -1) {
+		return undefined;
+	}
+	const description = fromUTF8(
+		toUint8(frame.data, 3 + mimeTypeEndIndex, descriptionEndIndex)
+	);
+
+	let data;
+	if (mimeType === '-->') {
+		data = fromUTF8(
+			toUint8(frame.data, 4 + mimeTypeEndIndex + descriptionEndIndex)
+		);
+	} 
+	else {
+		data = toArrayBuffer(
+			frame.data.subarray(4 + mimeTypeEndIndex + descriptionEndIndex)
+		);
+	}
+
+	metadataFrame.mimeType = mimeType;
+	metadataFrame.pictureType = pictureType;
+	metadataFrame.description = description;
+	metadataFrame.data = data;
+	return metadataFrame;
+}
+
+function fromUTF8(data?: BufferSource) {
+	if (!data) {
+		return '';
+	}
+
+	let uint8 = toUint8(data);
+	// If present, strip off the UTF-8 BOM.
+	if (uint8[0] == 0xef && uint8[1] == 0xbb && uint8[2] == 0xbf) {
+		uint8 = uint8.subarray(3);
+	}
+
+	let decoded = '';
+	for (let i = 0; i < uint8.length; ++i) {
+		// By default, the 'replacement character' codepoint.
+		let codePoint = 0xfffd;
+
+		// Top bit is 0, 1-byte encoding.
+		if ((uint8[i] & 0x80) == 0) {
+			codePoint = uint8[i];
+
+			// Top 3 bits of byte 0 are 110, top 2 bits of byte 1 are 10,
+			// 2-byte encoding.
+		} 
+		else if (
+			uint8.length >= i + 2 &&
+			(uint8[i] & 0xe0) == 0xc0 &&
+			(uint8[i + 1] & 0xc0) == 0x80
+		) {
+			codePoint = ((uint8[i] & 0x1f) << 6) | (uint8[i + 1] & 0x3f);
+			i += 1; // Consume one extra byte.
+
+			// Top 4 bits of byte 0 are 1110, top 2 bits of byte 1 and 2 are 10,
+			// 3-byte encoding.
+		} 
+		else if (
+			uint8.length >= i + 3 &&
+			(uint8[i] & 0xf0) == 0xe0 &&
+			(uint8[i + 1] & 0xc0) == 0x80 &&
+			(uint8[i + 2] & 0xc0) == 0x80
+		) {
+			codePoint =
+				((uint8[i] & 0x0f) << 12) |
+				((uint8[i + 1] & 0x3f) << 6) |
+				(uint8[i + 2] & 0x3f);
+			i += 2; // Consume two extra bytes.
+
+			// Top 5 bits of byte 0 are 11110, top 2 bits of byte 1, 2 and 3 are 10,
+			// 4-byte encoding.
+		} 
+		else if (
+			uint8.length >= i + 4 &&
+			(uint8[i] & 0xf1) == 0xf0 &&
+			(uint8[i + 1] & 0xc0) == 0x80 &&
+			(uint8[i + 2] & 0xc0) == 0x80 &&
+			(uint8[i + 3] & 0xc0) == 0x80
+		) {
+			codePoint =
+				((uint8[i] & 0x07) << 18) |
+				((uint8[i + 1] & 0x3f) << 12) |
+				((uint8[i + 2] & 0x3f) << 6) |
+				(uint8[i + 3] & 0x3f);
+			i += 3; // Consume three extra bytes.
+		}
+
+		// JavaScript strings are a series of UTF-16 characters.
+		if (codePoint <= 0xffff) {
+			decoded += String.fromCharCode(codePoint);
+		} 
+		else {
+			// UTF-16 surrogate-pair encoding, based on
+			// https://en.wikipedia.org/wiki/UTF-16#Description
+			const baseCodePoint = codePoint - 0x10000;
+			const highPart = baseCodePoint >> 10;
+			const lowPart = baseCodePoint & 0x3ff;
+			decoded += String.fromCharCode(0xd800 + highPart);
+			decoded += String.fromCharCode(0xdc00 + lowPart);
+		}
+	}
+
+	return decoded;
+}
+
+export function toArrayBuffer(view: ArrayBuffer | TypedArray): ArrayBuffer{
+	if (view instanceof ArrayBuffer) {
+		return view;
+	} 
+	else {
+		if (view.byteOffset == 0 && view.byteLength == view.buffer.byteLength) {
+			// This is a TypedArray over the whole buffer.
+			return view.buffer;
+		}
+		// This is a 'view' on the buffer.  Create a new buffer that only contains
+		// the data.  Note that since this isn't an ArrayBuffer, the 'new' call
+		// will allocate a new buffer to hold the copy.
+		return new Uint8Array(view).buffer;
+	}
+}

lib/src/id3/util/isId3Header.ts

@@ -45,6 +45,5 @@ export function isId3Header(data: Uint8Array, offset: number): boolean {
 			}
 		}
 	}
-
 	return false;
 }

lib/src/id3/util/utf8.ts

@@ -0,0 +1,56 @@
+import { isArrayBufferView } from 'util/types';
+
+export function toUint8(
+	data: BufferSource,
+	offset: number = 0,
+	length: number = Infinity
+) {
+	return view(data, offset, length, Uint8Array);
+}
+
+function view<T extends ArrayBufferView>(
+	data: BufferSource,
+	offset: number,
+	length: number,
+	Type: { new (buffer: ArrayBuffer, byteOffset: number, length: number): T }
+): T {
+	const buffer = unsafeGetArrayBuffer(data);
+	let bytesPerElement: any = 1;
+	if ('BYTES_PER_ELEMENT' in Type) {
+		bytesPerElement = Type.BYTES_PER_ELEMENT;
+	}
+	// Absolute end of the |data| view within |buffer|.
+	const dataOffset = isArrayBufferView(data) ? data.byteOffset : 0;
+	const dataEnd = ((dataOffset) + data.byteLength) / bytesPerElement;
+	// Absolute start of the result within |buffer|.
+	const rawStart = ((dataOffset) + offset) / bytesPerElement;
+	const start = Math.floor(Math.max(0, Math.min(rawStart, dataEnd)));
+	// Absolute end of the result within |buffer|.
+	const end = Math.floor(Math.min(start + Math.max(length, 0), dataEnd));
+	return new Type(buffer, start, end - start);
+}
+
+function unsafeGetArrayBuffer(view: BufferSource) {
+	if (view instanceof ArrayBuffer) {
+		return view;
+	}
+	else {
+		return view.buffer;
+	}
+}
+
+export function toArrayBuffer(view: BufferSource) {
+	if (view instanceof ArrayBuffer) {
+		return view;
+	}
+	else {
+		if (view.byteOffset == 0 && view.byteLength == view.buffer.byteLength) {
+			// This is a TypedArray over the whole buffer.
+			return view.buffer;
+		}
+		// This is a 'view' on the buffer.  Create a new buffer that only contains
+		// the data.  Note that since this isn't an ArrayBuffer, the 'new' call
+		// will allocate a new buffer to hold the copy.
+		return new Uint8Array(view.buffer).buffer;
+	}
+}