iopenpod 1.0.47__py3-none-any.whl

ArtworkDB_Parser/__init__.py

@@ -0,0 +1,3 @@
+from .parser import parse_artworkdb
+
+__all__ = ["parse_artworkdb"]

ArtworkDB_Parser/chunk_parser.py

@@ -0,0 +1,66 @@
+import struct
+from typing import Any
+
+
+def parse_chunk(data, offset) -> dict[str, Any]:
+    chunk_type = data[offset: offset + 4].decode("utf-8")
+    header_length = struct.unpack("<I", data[offset + 4: offset + 8])[0]
+    chunk_length = struct.unpack("<I", data[offset + 8: offset + 12])[0]
+
+    match chunk_type:
+        case "mhfd":
+            # Data file
+            from .mhfd_parser import parse_mhfd
+
+            result = parse_mhfd(data, offset, header_length, chunk_length)
+            return result
+        case "mhsd":
+            # Data Set
+            from .mhsd_parser import parse_mhsd
+
+            result = parse_mhsd(data, offset, header_length, chunk_length)
+            return result
+        case "mhli":
+            # Image List
+            from .mhli_parser import parse_mhli
+
+            result = parse_mhli(data, offset, header_length, chunk_length)
+            return result
+        case "mhii":
+            # Image Item
+            from .mhii_parser import parse_imageItem
+
+            result = parse_imageItem(data, offset, header_length, chunk_length)
+            return result
+        case "mhni":
+            # Image Name
+            from .mhni_parser import parse_mhni
+
+            result = parse_mhni(data, offset, header_length, chunk_length)
+            return result
+        case "mhla":
+            # Photo Album List
+            return {}
+        case "mhba":
+            # Photo Album
+            return {}
+        case "mhia":
+            # Photo Album Item
+            return {}
+        case "mhlf":
+            # File List
+            return {}
+        case "mhif":
+            # File Item
+            return {}
+        case "mhod":
+            # Data Object
+            from .mhod_parser import parse_mhod
+
+            result = parse_mhod(data, offset, header_length, chunk_length)
+            return result
+        case "mhaf":
+            # Unknown
+            return {}
+        case _:
+            raise ValueError(f"Unknown chunk type: {chunk_type}")

ArtworkDB_Parser/constants.py

@@ -0,0 +1,37 @@
+# maps the id used in mhsd to the proper header marker
+chunk_type_map = {
+    1: "mhli",  # Image List chunk
+    2: "mhla",  # Photo ALbum List chunk
+    3: "mhlf",  # File List Chunk
+}
+
+# maps the chunk header marker to a readable name
+# the identifier appears to be backward, I estimate that it should read like
+# DataBaseHeaderMarker(DBHM) and DataStructureHeaderMarker(DSHM) and
+# TrackListHeaderMarker(TLHM)...
+identifier_readable_map = {
+    "mhfd": "Data File",
+    "mhsd": "Data Set",
+    "mhli": "Image List",
+    "mhii": "Image Item",
+    "mhni": "Image Name",
+    "mhla": "Photo Album List",
+    "mhba": "Photo Album",
+    "mhia": "Photo Album Item",
+    "mhlf": "File List",
+    "mhif": "File List Item",
+    "mhod": "Data Object",
+}
+
+# maps the mhod type to its readable name
+# There are 2 groups of types of MHODs in the ArtworkDB:
+# container MHODs contain a MHNI as a child,
+# while 'normal' string MHODs contain a string.
+
+mhod_type_map = {
+    1: {"type": "String", "name": "Album Name"},
+    2: {"type": "Container", "name": "Thumbnail Image"},
+    3: {"type": "String", "name": "File Name"},
+    5: {"type": "Container", "name": "Full Res Image"},
+    6: {"type": "Container", "name": "UNK MHOD 6"},
+}

ArtworkDB_Parser/mhfd_parser.py

@@ -0,0 +1,61 @@
+import base64
+import struct
+from typing import Any
+
+
+def parse_mhfd(data, offset, header_length, chunk_length) -> dict[str, Any]:
+    from .chunk_parser import parse_chunk
+    from .constants import chunk_type_map
+
+    datafile: dict[str, Any] = {}
+
+    datafile["unk1"] = struct.unpack(
+        "<I", data[offset + 12:offset + 16])[0]  # always 0
+    datafile["unk2"] = struct.unpack(
+        "<I", data[offset + 16:offset + 20])[0]  # 1 until iTunes 4.9. 2 after
+
+    datafile["childCount"] = struct.unpack("<I", data[offset + 20:offset + 24])[0]
+
+    datafile["unk3"] = struct.unpack(
+        "<I", data[offset + 24:offset + 28])[0]  # always 0
+
+    # ID of last mhii + 1. On iPod video seems to be last mhii + mhba count + 1
+    datafile["next_mhii_id"] = struct.unpack(
+        "<I", data[offset + 28:offset + 32])[0]
+
+    datafile["unk4"] = struct.unpack("<Q", data[offset + 32:offset + 40])[0]
+    datafile["unk5"] = struct.unpack("<Q", data[offset + 40:offset + 48])[0]
+
+    datafile["unk6"] = struct.unpack(
+        "<I", data[offset + 48:offset + 52])[0]  # always 2
+    datafile["unk7"] = struct.unpack(
+        "<I", data[offset + 52:offset + 56])[0]  # always 0
+    datafile["unk8"] = struct.unpack(
+        "<I", data[offset + 56:offset + 60])[0]  # always 0
+
+    datafile["unk9"] = struct.unpack("<I", data[offset + 60:offset + 64])[0]
+    datafile["unk10"] = struct.unpack("<I", data[offset + 64:offset + 68])[0]
+
+    # parse children
+    next_offset = offset + header_length
+    for i in range(datafile["childCount"]):
+        childResult = parse_chunk(data, next_offset)
+        next_offset = childResult["nextOffset"]
+        resultData = childResult["result"]
+        resultType = childResult["datasetType"]
+        datafile[chunk_type_map[resultType]] = resultData
+
+    # Convert byte fields to base64 for JSON serialization
+    def replace_bytes_with_base64(data: Any) -> Any:
+        if isinstance(data, dict):  # If it's a dictionary, process each key-value pair
+            return {key: replace_bytes_with_base64(value) for key, value in data.items()}
+        elif isinstance(data, list):  # If it's a list, process each item
+            return [replace_bytes_with_base64(item) for item in data]
+        elif isinstance(data, bytes):  # If it's bytes, encode to Base64
+            return base64.b64encode(data).decode("utf-8")
+        else:
+            return data  # If it's not bytes, return as-is
+
+    cleaned_database = replace_bytes_with_base64(datafile)
+
+    return {"nextOffset": next_offset, "result": cleaned_database}

ArtworkDB_Parser/mhii_parser.py

@@ -0,0 +1,52 @@
+import struct
+
+
+def parse_imageItem(data, offset, header_length, chunk_length) -> dict:
+    from .chunk_parser import parse_chunk
+    from .constants import mhod_type_map
+
+    image = {}
+
+    childCount = struct.unpack("<I", data[offset + 12: offset + 16])[0]
+
+    image["img_id"] = struct.unpack("<I", data[offset + 16: offset + 20])[0]
+
+    # First mhii is 0x40, second is 0x41, ...
+    # (on mobile phones the first mhii appears to be 0x64, second 0x65, ...)
+
+    image["songId"] = struct.unpack("<Q", data[offset + 20: offset + 28])[0]
+    # unique ID that matches the db_track_id field in the iTunesDB Track Item record.
+    # this is what is used to map the ArtworkDB items to iTunesDB Items.
+
+    image["unk1"] = struct.unpack(
+        "<I", data[offset + 28: offset + 32])[0]  # always 0
+
+    image["rating"] = struct.unpack("<I", data[offset + 32: offset + 36])[
+        0
+    ]  # iPhoto rating x20
+
+    image["unk2"] = struct.unpack(
+        "<I", data[offset + 36: offset + 40])[0]  # always 0
+
+    image["originalDate"] = struct.unpack(
+        "<I", data[offset + 40: offset + 44])[0]
+    # always 0 in ArtworkDB. creation timestamp of file in photo database.
+
+    image["exifTakenDate"] = struct.unpack(
+        "<I", data[offset + 44: offset + 48])[0]
+    # always 0 in ArtworkDB. timestamp of taken time probably from exif in photo db.
+
+    image["srcImgSize"] = struct.unpack(
+        "<I", data[offset + 48: offset + 52])[0]
+    # size in bytes of the original source image.
+
+    # Parse Children
+    next_offset = offset + header_length
+    for i in range(childCount):
+        response = parse_chunk(data, next_offset)
+        next_offset = response["nextOffset"]
+
+        mhodData = response["result"]
+        image[mhod_type_map[mhodData["mhodType"]]["name"]] = mhodData
+
+    return {"nextOffset": offset + chunk_length, "result": image}

ArtworkDB_Parser/mhli_parser.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+
+def parse_mhli(data, offset, header_length, imageCount) -> dict[str, Any]:
+    from .chunk_parser import parse_chunk
+
+    imageList = []
+
+    # Parse Children
+    next_offset = offset + header_length
+    for i in range(imageCount):
+        response = parse_chunk(data, next_offset)
+        next_offset = response["nextOffset"]
+        imageList.append(response["result"])
+
+    return {"nextOffset": next_offset, "result": imageList}

ArtworkDB_Parser/mhni_parser.py

@@ -0,0 +1,196 @@
+import struct
+
+from ipod_device import ITHMB_FORMAT_MAP
+from ipod_device.artwork_presets import artwork_format_candidates
+
+
+def _expected_img_size_bytes(candidate) -> int:
+    pf = candidate.pixel_format
+    if pf in (
+        "RGB565_LE",
+        "RGB565_BE",
+        "RGB565_BE_90",
+        "UYVY",
+        "RGB555_LE",
+        "RGB555_BE",
+    ):
+        return candidate.row_bytes * candidate.height
+    if pf.startswith("REC_RGB555"):
+        return candidate.row_bytes * candidate.height
+    if pf == "I420_LE":
+        w = candidate.width & ~1
+        h = candidate.height & ~1
+        return (w * h * 3) // 2
+    if pf == "JPEG":
+        return 0
+    return 0
+
+
+def parse_mhni(data, offset, header_length, chunk_length) -> dict:
+    from .chunk_parser import parse_chunk
+
+    imageName = {}
+
+    childCount = struct.unpack("<I", data[offset + 12: offset + 16])[0]
+    # a type 3 mhod
+
+    imageName["correlationID"] = struct.unpack(
+        "<I", data[offset + 16: offset + 20])[0]
+    # maps to mhif correlationID. generates name of the file
+    # Also serves as the format_id to identify image format (libgpod approach)
+
+    imageName["ithmbOffset"] = struct.unpack(
+        "<I", data[offset + 20: offset + 24])[0]
+    # where the image data starts in the .ithmb file
+
+    imageName["imgSize"] = struct.unpack(
+        "<I", data[offset + 24: offset + 28])[0]
+    # in bytes
+
+    imageName["verticalPadding"] = struct.unpack("<h", data[offset + 28: offset + 30])[
+        0
+    ]
+    imageName["horizontalPadding"] = struct.unpack(
+        "<h", data[offset + 30: offset + 32]
+    )[0]
+
+    imageName["imageHeight"] = struct.unpack(
+        "<H", data[offset + 32: offset + 34])[0]
+    imageName["imageWidth"] = struct.unpack(
+        "<H", data[offset + 34: offset + 36])[0]
+
+    imageName["unk1"] = struct.unpack("<I", data[offset + 36: offset + 40])[0]
+    # always 0
+
+    imageName["imgSize2"] = struct.unpack(
+        "<I", data[offset + 40: offset + 44])[0]
+    # Same as imgSize, seen after iTunes 7.4
+
+    # Estimate pixmap dimensions (for debugging/fallback)
+    imageName["estimatedPixmapHeight"] = (
+        imageName["verticalPadding"] + imageName["imageHeight"]
+    )
+    imageName["estimatedPixmapWidth"] = (
+        imageName["horizontalPadding"] + imageName["imageWidth"]
+    )
+
+    image_format = None
+
+    format_id = imageName["correlationID"]
+    candidates = artwork_format_candidates()
+    same_id_candidates = [
+        candidate
+        for candidate in candidates
+        if candidate.format_id == format_id
+    ]
+    est_w = imageName["estimatedPixmapWidth"]
+    est_h = imageName["estimatedPixmapHeight"]
+    img_size = imageName["imgSize"]
+
+    # Prefer correlationID mapping only when it is plausibly compatible with
+    # observed MHNI geometry or payload size. Some legacy/corrupt databases
+    # carry mismatched correlation IDs (e.g. 140x140 metadata for ~57x58 data).
+    if same_id_candidates:
+        best_match = None
+        best_match_score = float("inf")
+        for af in same_id_candidates:
+            expected = _expected_img_size_bytes(af)
+            corr_exact = expected > 0 and expected == img_size
+            corr_close = (
+                est_w > 0
+                and est_h > 0
+                and (
+                    (abs(est_w - af.width) <= 2 and abs(est_h - af.height) <= 2)
+                    or (abs(est_w - af.height) <= 2 and abs(est_h - af.width) <= 2)
+                )
+            )
+            # For variable-sized payloads (e.g. JPEG), trust correlation ID + geometry.
+            if expected == 0 and corr_close:
+                corr_exact = True
+            if not (corr_exact or corr_close):
+                continue
+
+            size_delta = abs(img_size - expected) if expected > 0 else 0
+            dim_delta = abs(est_w - af.width) + abs(est_h - af.height)
+            score = size_delta + dim_delta
+            if score < best_match_score:
+                best_match = af
+                best_match_score = score
+
+        if best_match is not None:
+            image_format = {
+                "height": best_match.height,
+                "width": best_match.width,
+                "format": best_match.pixel_format,
+                "description": best_match.description,
+                "format_id": format_id,
+            }
+
+    if image_format is None:
+        af = ITHMB_FORMAT_MAP.get(format_id)
+    else:
+        af = None
+
+    if image_format is None and af is not None:
+        expected = _expected_img_size_bytes(af)
+        corr_exact = expected > 0 and expected == img_size
+        corr_close = (
+            est_w > 0
+            and est_h > 0
+            and (
+                (abs(est_w - af.width) <= 2 and abs(est_h - af.height) <= 2)
+                or (abs(est_w - af.height) <= 2 and abs(est_h - af.width) <= 2)
+            )
+        )
+        # For variable-sized payloads (e.g. JPEG), trust correlation ID + geometry.
+        if expected == 0 and corr_close:
+            corr_exact = True
+        if corr_exact or corr_close:
+            image_format = {
+                "height": af.height,
+                "width": af.width,
+                "format": af.pixel_format,
+                "description": af.description,
+                "format_id": format_id,
+            }
+
+    if image_format is None:
+        # Fallback: choose the candidate that best matches observed geometry
+        # and payload pixel count.
+        best_candidate = None
+        best_score = float("inf")
+
+        for candidate in candidates:
+            dim_diff = abs(est_h - candidate.height) + abs(est_w - candidate.width)
+            expected = _expected_img_size_bytes(candidate)
+            if expected > 0:
+                size_delta = abs(img_size - expected)
+                score = dim_diff + (
+                    size_delta / max(1, candidate.row_bytes, candidate.width)
+                )
+            else:
+                score = dim_diff
+            if score < best_score:
+                best_score = score
+                best_candidate = candidate
+
+        if best_candidate is not None:
+            image_format = {
+                "height": best_candidate.height,
+                "width": best_candidate.width,
+                "format": best_candidate.pixel_format,
+                "description": best_candidate.description,
+                "format_id": best_candidate.format_id,
+                "score": best_score,
+            }
+
+    imageName["image_format"] = image_format
+
+    # parse children
+    next_offset = offset + header_length
+    for i in range(childCount):
+        response = parse_chunk(data, next_offset)
+        next_offset = response["nextOffset"]
+        imageName[response["result"]["mhodType"]] = response["result"]
+
+    return {"nextOffset": offset + chunk_length, "result": imageName}

ArtworkDB_Parser/mhod_parser.py

@@ -0,0 +1,73 @@
+import struct
+
+
+def parse_mhod(data, offset, header_length, chunk_length) -> dict:
+    from .constants import mhod_type_map
+    from .chunk_parser import parse_chunk
+
+    dataObject = {}
+
+    dataObject["mhodType"] = struct.unpack(
+        "<H", data[offset + 12: offset + 14])[0]
+
+    # unk0 = struct.unpack("<B", data[offset + 14: offset + 15])[0]  # always 0
+
+    # paddingLength = struct.unpack("<B", data[offset + 15: offset + 16])[0]
+    # all MHOD pad to be be a multiple of 4. the length will be 0,1,3
+
+    # There is a bug in the iPod code that causes an MHBA to have an MHOD
+    # of type 2 that is ont a container but is actually a string
+
+    # MHOD type 2 contain a MHNI that cotains a MHOD type 3 with a thmbnl ref
+    # MHOD type 5 contain a MHNI that cotains a MHOD type 3 with a fulrez ref
+
+    if dataObject["mhodType"] not in mhod_type_map:
+        return {
+            "nextOffset": offset + chunk_length,
+            "result": {"mhodType": dataObject["mhodType"], "_unknown": True},
+        }
+
+    match mhod_type_map[dataObject["mhodType"]]["type"]:
+        case "String":
+            content_offset = offset + header_length
+
+            stringByteLength = struct.unpack(
+                "<I", data[content_offset: content_offset + 4])[0]
+
+            # Encoding byte at content_offset+4 (ArtworkDB_MhodHeaderString.encoding)
+            # Per libgpod db-itunes-parser.h: 0,1 = UTF-8; 2 = UTF-16-LE
+            encoding = data[content_offset + 4]
+
+            # content_offset+8: unknown (always 0)
+
+            stringContent = data[
+                content_offset + 12: content_offset + 12 + stringByteLength]
+
+            # padding would be offset+stringByteLength:offset+paddingLength
+            # but for the purposes of parsing it is not needed.
+
+            if encoding == 2:
+                string_decode = stringContent.decode("utf-16-le", errors="replace")
+            else:
+                string_decode = stringContent.decode("utf-8", errors="replace")
+
+            dataObject[mhod_type_map[dataObject["mhodType"]]
+                       ["name"]] = string_decode
+
+            return {"nextOffset": offset + chunk_length, "result": dataObject}
+        case "Container":
+
+            # parse children (MHNI)
+            next_offset = offset + header_length
+            childResult = parse_chunk(data, next_offset)
+
+            dataObject[mhod_type_map[dataObject["mhodType"]]
+                       ["name"]] = childResult
+
+            return {"nextOffset": offset + chunk_length, "result": dataObject}
+
+        case _:
+            return {
+                "nextOffset": offset + chunk_length,
+                "result": {"mhodType": "ERROR"},
+            }

ArtworkDB_Parser/mhsd_parser.py

@@ -0,0 +1,16 @@
+import struct
+
+
+def parse_mhsd(data, offset, header_length, chunk_length) -> dict:
+    from .chunk_parser import parse_chunk
+
+    # ArtworkDB MHSD index is u16, not u32 like iTunesDB
+    # (per libgpod ArtworkDB_MhsdHeader struct)
+    datasetType = struct.unpack("<H", data[offset + 12:offset + 14])[0]
+
+    # Parse Child
+    next_offset = offset + header_length
+    childResult = parse_chunk(data, next_offset)
+    # Extract the actual result from the wrapper
+    result = childResult.get("result", childResult)
+    return {"datasetType": datasetType, "result": result, "nextOffset": offset + chunk_length}

ArtworkDB_Parser/parser.py

@@ -0,0 +1,15 @@
+def parse_artworkdb(file) -> dict:
+    from .chunk_parser import parse_chunk
+
+    if isinstance(file, str):  # If it's a file path, open the file
+        with open(file, "rb") as f:
+            data = f.read()
+    elif hasattr(file, "read"):  # If it's a file-like object, read it directly
+        data = file.read()
+    else:
+        raise TypeError("file must be a path (str) or a file-like object")
+
+    result = parse_chunk(data, 0)
+
+    # Return just the parsed data, not the wrapper with nextOffset
+    return result.get("result", result)

ArtworkDB_Writer/__init__.py

@@ -0,0 +1,63 @@
+"""
+ArtworkDB Writer for iPod Classic/Nano.
+
+Writes ArtworkDB binary files and .ithmb image files from PC music
+file embedded album art.
+
+Usage:
+    from ArtworkDB_Writer import write_artworkdb
+
+    # pc_file_paths maps track db_track_id → PC source file path
+    db_track_id_to_art = write_artworkdb(
+        ipod_path="/media/ipod",
+        tracks=track_list,
+        pc_file_paths={12345: "/home/user/Music/song.mp3", ...},
+    )
+
+    # Then set mhiiLink and artworkSize on each track in iTunesDB
+    for track in tracks:
+        art_info = db_track_id_to_art.get(track.db_track_id)
+        if art_info:
+            img_id, src_size = art_info
+            track.mhii_link = img_id
+            track.artwork_size = src_size
+"""
+
+from .artwork_writer import write_artworkdb, ArtworkEntry
+from .art_extractor import extract_art, art_hash
+from .rgb565 import (
+    convert_art_for_ipod,
+    image_from_bytes,
+    rgb888_to_rgb565,
+    get_artwork_formats,
+    IPOD_CLASSIC_FORMATS,
+    IPOD_NANO_1G2G_FORMATS,
+    IPOD_PHOTO_FORMATS,
+    IPOD_VIDEO_FORMATS,
+    IPOD_NANO_4G_FORMATS,
+    IPOD_NANO_5G_FORMATS,
+    ALL_KNOWN_FORMATS,
+)
+# Re-export canonical format lookups from ipod_device
+from ipod_device import ITHMB_FORMAT_MAP, ITHMB_SIZE_MAP, ithmb_formats_for_device
+
+__all__ = [
+    'write_artworkdb',
+    'ArtworkEntry',
+    'extract_art',
+    'art_hash',
+    'convert_art_for_ipod',
+    'image_from_bytes',
+    'rgb888_to_rgb565',
+    'get_artwork_formats',
+    'IPOD_CLASSIC_FORMATS',
+    'IPOD_NANO_1G2G_FORMATS',
+    'IPOD_PHOTO_FORMATS',
+    'IPOD_VIDEO_FORMATS',
+    'IPOD_NANO_4G_FORMATS',
+    'IPOD_NANO_5G_FORMATS',
+    'ALL_KNOWN_FORMATS',
+    'ITHMB_FORMAT_MAP',
+    'ITHMB_SIZE_MAP',
+    'ithmb_formats_for_device',
+]