exp-runtime-formats 0.5.0__py3-none-any.whl

exp_runtime/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the tools as ``python -m exp_runtime``."""
+
+from .cli import main
+
+main()

exp_runtime/atlas.py

@@ -0,0 +1,203 @@
+"""Packed RGBA sprite atlases used by the native minigame renderer.
+
+This is the CS sprite-atlas path (000507b8 / 000503dc), separate from
+ImagePack's literal-image path. All dimensions and extents are bounded.
+"""
+from dataclasses import dataclass
+
+from .exp import MAX_PAYLOAD
+from .ui_assets import Raster, UIAssetError, _Reader
+
+
+@dataclass(frozen=True)
+class AtlasFrame:
+    x: int
+    y: int
+    width: int
+    height: int
+    stored_width: int
+    stored_height: int
+
+
+@dataclass(frozen=True)
+class SpriteAtlas:
+    flags: int
+    sequences: tuple[tuple[int, ...], ...]
+    parts: tuple[tuple[tuple[int, int, int], ...], ...]
+    transforms: tuple[tuple[int, int], ...]
+    frames: tuple[AtlasFrame, ...]
+    image: Raster
+
+    @classmethod
+    def parse(cls, data):
+        r = _Reader(data)
+        flags, capacity, count = r.integer('B'), r.count(), r.count('b')
+        if flags & ~0x3f:
+            raise UIAssetError('Unsupported sprite-atlas flags')
+        sequences = []
+        if count:
+            base, total = r.integer(), r.count()
+            for _ in range(count):
+                sequences.append(tuple(base + r.integer('h' if flags & 4 else 'b')
+                                       for __ in range(r.count('b'))))
+            if sum(map(len, sequences)) != total:
+                raise UIAssetError('Inconsistent atlas sequences')
+        count, total = r.count(), r.count()
+        parts = []
+        for _ in range(count):
+            parts.append(tuple((r.integer('h' if flags & 1 else 'b'),
+                                r.integer('h' if flags & 2 else 'b'),
+                                r.integer('h' if flags & 2 else 'b'))
+                               for __ in range(r.count('b'))))
+        if sum(map(len, parts)) != total:
+            raise UIAssetError('Inconsistent atlas parts')
+        transforms = tuple(r.unpack('hb') for _ in range(r.count()))
+        scale, size, count = r.integer(), r.count(), r.count()
+        if scale <= 0 or size <= 0 or size * size * 4 > MAX_PAYLOAD or count != capacity:
+            raise UIAssetError('Invalid sprite-atlas dimensions')
+        frames = []
+        for _ in range(count):
+            x, y, w, h, sw, sh = r.unpack('hhhhhh')
+            x, y = x * scale, y * scale
+            if (min(x, y, w, h, sw, sh) < 0 or w * h * 4 > MAX_PAYLOAD
+                    or x + sw > size or y + sh > size):
+                raise UIAssetError('Sprite frame is outside its atlas')
+            frames.append(AtlasFrame(x, y, w, h, sw, sh))
+        data = r.take(size * size * 4)
+        r.finish()
+        # 000503dc reverses each stored A,B,G,R quadruple before upload.
+        rgba = bytearray(len(data))
+        rgba[0::4], rgba[1::4], rgba[2::4], rgba[3::4] = data[3::4], data[2::4], data[1::4], data[0::4]
+        for frame, transform in transforms:
+            if not 0 <= frame < count or not 0 <= transform <= 7:
+                raise UIAssetError('Invalid atlas transform')
+        for group in parts:
+            for index, _, __ in group:
+                if not (-len(parts) <= index < count):
+                    raise UIAssetError('Invalid atlas part reference')
+        return cls(flags, tuple(sequences), tuple(parts), transforms, tuple(frames),
+                   Raster(size, size, bytes(rgba)))
+
+    def raster(self, index):
+        """Decode a positive literal frame; composites retain signed references."""
+        if not 0 <= index < len(self.frames):
+            raise UIAssetError('Absent atlas frame')
+        f = self.frames[index]
+        if f.width != f.stored_width or f.height != f.stored_height:
+            raise UIAssetError('Scaled atlas frame requires renderer resampling')
+        row_size = f.width * 4
+        pixels = b''.join(self.image.pixels[(y * self.image.width + f.x) * 4:
+                                          (y * self.image.width + f.x) * 4 + row_size]
+                          for y in range(f.y, f.y + f.height))
+        result = Raster(f.width, f.height, pixels)
+        for frame, transform in self.transforms:
+            if frame == index:
+                result = result.transformed(transform)
+        return result
+
+    def literals(self, index):
+        """Flatten signed composite references, preserving painter order/origin."""
+        result = []
+
+        def visit(ref, x, y, ancestors):
+            if ref >= 0:
+                if ref >= len(self.frames) or len(result) >= 4096:
+                    raise UIAssetError('Invalid or oversized atlas composite')
+                result.append((ref, x, y))
+                return
+            if ref in ancestors or len(ancestors) >= 64 or ~ref >= len(self.parts):
+                raise UIAssetError('Invalid or cyclic atlas composite')
+            for child, dx, dy in self.parts[~ref]:
+                visit(child, x + dx, y + dy, ancestors + (ref,))
+
+        visit(index, 0, 0, ())
+        return tuple(result)
+
+
+@dataclass(frozen=True)
+class AtlasFont:
+    """000538ac: six-byte header, then (byte, s16 x, s16 y, s8 width)."""
+    space_width: int
+    style: int
+    tracking: int
+    height: int
+    glyphs: dict[int, tuple[int, int, int]]
+
+    @classmethod
+    def parse(cls, data, atlas):
+        r = _Reader(data)
+        space, style, tracking = r.integer('b'), r.integer('B'), r.integer('b')
+        count, height = r.count(), r.integer('b')
+        if height <= 0 or space < 0 or count > 256:
+            raise UIAssetError('Invalid atlas font header')
+        glyphs = {}
+        for _ in range(count):
+            code, x, y, width = r.unpack('Bhhb')
+            if min(x, y, width) < 0 or x + width > atlas.width or y + height > atlas.height:
+                raise UIAssetError('Font glyph is outside its atlas')
+            glyphs[code] = x, y, width
+        r.finish()
+        return cls(space, style, tracking, height, glyphs)
+
+    def glyph(self, char):
+        code = ord(char)
+        code = {0x91: 39, 0x92: 39, 0x93: 34, 0x94: 34, 0x96: 45}.get(code, code)
+        if code not in self.glyphs:
+            if 97 <= code <= 122 or 224 <= code <= 252:
+                code -= 32
+            elif 65 <= code <= 90 or 192 <= code <= 220:
+                code += 32
+        return self.glyphs.get(code)
+
+    @property
+    def line_gap(self):
+        # 000538ac stores header byte 1 at +0x139; 00054490 adds it to
+        # each line's height. The older parser called this byte "style".
+        return self.style if self.style < 128 else self.style - 256
+
+    def char_width(self, char, monospace=None):
+        if monospace is not None:
+            return self.char_width(monospace)
+        glyph = self.glyph(char)
+        return glyph[2] if glyph is not None else self.space_width
+
+    def width(self, text, monospace=None):
+        """000535fc: trim leading spaces, omit the last tracking interval."""
+        return max((max(0, sum(self.char_width(c, monospace) + self.tracking for c in line)
+                        - self.tracking) if line else 0
+                    for line in text.lstrip(' ').split('\n')), default=0)
+
+    def wrap(self, text, width):
+        """00054490: byte glyph advances, space wrapping and explicit newlines."""
+        if width <= 0:
+            raise UIAssetError('Atlas text width must be positive')
+        lines = []
+        while text:
+            text = text.lstrip(' ')
+            if not text:
+                break
+            end, advance = 0, 0
+            while end < len(text) and text[end] != '\n':
+                glyph_width = self.char_width(text[end])
+                if glyph_width > width:
+                    raise UIAssetError('Atlas text column cannot fit a glyph')
+                if advance + glyph_width > width:
+                    break
+                advance += glyph_width + self.tracking
+                end += 1
+            if end == len(text):
+                lines.append(text)
+                break
+            if text[end] == '\n':
+                lines.append(text[:end])
+                text = text[end + 1:]
+            else:
+                space = text.rfind(' ', 0, end + 1)
+                if space > 0:
+                    end = space
+                lines.append(text[:end])
+                text = text[end:]
+        return tuple(lines)
+
+    def text_height(self, lines):
+        return len(lines) * (self.height + self.line_gap) - self.line_gap if lines else 0

exp_runtime/cli.py

@@ -0,0 +1,186 @@
+"""Import, inspect and launch player-supplied EXP game content."""
+
+import argparse
+from dataclasses import asdict
+from importlib.util import find_spec
+import json
+import logging
+import sys
+import tempfile
+
+from pathlib import Path
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser with all subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="exp-tool",
+        description="Inspect EXP files and play SHS or Cause of Death with your own game data.",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (-v for INFO, -vv for DEBUG).",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    inspect_parser = subparsers.add_parser('inspect', help='Inspect an EXP without installing the engine or games.')
+    inspect_parser.add_argument('archive', type=Path)
+    extract_parser = subparsers.add_parser('extract', help='Extract EXP resources by numeric ID into a new directory.')
+    extract_parser.add_argument('archive', type=Path)
+    extract_parser.add_argument('--output', type=Path, required=True)
+
+    trace_parser = subparsers.add_parser(
+        "trace", help="Execute KiWi to the first pending action and print a JSON trace.",
+    )
+    trace_parser.add_argument("archive", type=Path, help="Path to the .exp archive.")
+    trace_parser.add_argument("--max-steps", type=int, default=100_000)
+    trace_parser.add_argument("--max-events", type=int, default=10_000)
+    trace_parser.add_argument('--game', choices=('shs', 'cod'), default='shs', help='Native host profile (default: shs).')
+
+    import_parser = subparsers.add_parser("import", help="Create a local library from your APK or IPA and episode files.")
+    source = import_parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--apk", type=Path, help="Your SHS Android 1.0.9 APK.")
+    source.add_argument("--ipa", type=Path, help="Your SHS or Cause of Death IPA with compatible game assets.")
+    import_parser.add_argument('--game', choices=('shs', 'cod'), help='Require assets for this game (otherwise detected).')
+    import_parser.add_argument("--music-apk", type=Path,
+                               help="Optional Android 1.0.9 APK supplying missing IPA music.")
+    import_parser.add_argument("--episodes", type=Path, nargs="+", action="extend", default=[],
+                               help="EXP files, episode ZIPs/RARs or directories; subfolders are scanned recursively.")
+    import_parser.add_argument("--library", type=Path, required=True,
+                               help="New library directory for this game.")
+
+    list_parser = subparsers.add_parser("list", help="List episodes in a local content library.")
+    list_parser.add_argument("--library", type=Path, default=Path(".shs-library"))
+    from .languages import TITLE_LANGUAGES
+    list_parser.add_argument('--title-language', choices=TITLE_LANGUAGES,
+                             help='Episode title language; defaults to the library preference. Does not translate story text.')
+
+    music_parser = subparsers.add_parser("add-music", help="Add missing music to an existing IPA library.")
+    music_parser.add_argument("--apk", type=Path, required=True, help="Your SHS Android 1.0.9 APK.")
+    music_parser.add_argument("--library", type=Path, required=True, help="Existing IPA library.")
+
+    play_parser = subparsers.add_parser("play", help="Open the main menu, or start a selected episode.")
+    play_parser.add_argument("--library", type=Path, help="Content library; defaults to the existing local library or user application data.")
+    play_parser.add_argument("--episode", help="Start directly: unique ID prefix, filename, or title from list.")
+    saves = play_parser.add_mutually_exclusive_group()
+    saves.add_argument("--resume", action="store_true", help="Load this episode's local save slot.")
+    saves.add_argument("--load", type=Path, help="Load a specific runtime JSON save.")
+    play_parser.add_argument("--no-audio", action="store_true")
+    play_parser.add_argument('--game', choices=('shs', 'cod'), help='Open this game directly instead of the chooser.')
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Configure logging
+    log_level = logging.WARNING
+    if args.verbose >= 2:
+        log_level = logging.DEBUG
+    elif args.verbose >= 1:
+        log_level = logging.INFO
+    logging.basicConfig(level=log_level, format="%(levelname)s: %(message)s")
+
+    if args.command in ('inspect', 'extract'):
+        from .exp import ContentError, ExpArchive
+        try:
+            archive = ExpArchive(args.archive.read_bytes())
+            if args.command == 'inspect':
+                result = dict(resources=sorted(archive.entries), scripts=sorted(archive.programs()))
+                if 1 in archive.entries:
+                    result['metadata'] = asdict(archive.metadata())
+                print(json.dumps(result, indent=2, ensure_ascii=False))
+            else:
+                destination = args.output
+                if destination.exists():
+                    raise ContentError(f'Output already exists: {destination}; choose a new directory')
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                # A corrupt record must not leave a partial extraction. IDs
+                # are validated integers; original archive paths are not used.
+                with tempfile.TemporaryDirectory(dir=destination.parent, prefix='.exp-extract-') as temporary:
+                    staged = Path(temporary) / 'resources'
+                    staged.mkdir()
+                    for resource in archive.entries:
+                        (staged / f'{resource}.bin').write_bytes(archive.read(resource))
+                    staged.rename(destination)
+                print(f'Extracted {len(archive.entries)} resources into {destination}')
+        except (ContentError, OSError) as error:
+            parser.error(str(error))
+        return
+
+    if args.command in ('import', 'list', 'play', 'add-music', 'trace'):
+        if find_spec('exp_runtime.engine') is None:
+            parser.error('This command needs the engine and a game adapter. '
+                         'Install "exp-runtime[engine,shs]" or "exp-runtime[engine,cod]".')
+    if args.command == 'play' and find_spec('exp_runtime.application') is None:
+        parser.error('The player is not installed. Install "exp-runtime[player]".')
+
+    if args.command in ("import", "list", "play", "add-music"):
+        from .content import ContentError, ContentLibrary, import_game
+        from .runtime import SaveError
+        from .vm import VMError
+
+        try:
+            if args.command == "import":
+                manifest = import_game(args.apk or args.ipa, args.episodes, args.library,
+                                       music_apk=args.music_apk, game=args.game)
+                print(f"Imported {len(manifest['episodes'])} episodes into {args.library}")
+                return
+            if args.command == 'play':
+                if (args.load or args.resume) and not args.episode:
+                    parser.error('--load and --resume require --episode; omit them to use the main menu')
+                try:
+                    from .application import Application
+                except ModuleNotFoundError as error:
+                    if error.name != 'pygame':
+                        raise
+                    parser.error('Desktop support is not installed. Run uv sync --extra desktop '
+                                 'or install the package with its [desktop] extra.')
+                app = Application(args.library, audio=not args.no_audio, game_key=args.game)
+                try:
+                    if args.episode:
+                        if not app.library:
+                            raise ContentError(app.message or 'Import your APK or IPA before selecting an episode')
+                        app.selected = app.library.select(args.episode)['id']
+                        app.start(resume=args.resume, load_path=args.load)
+                except Exception:
+                    app.close()
+                    raise
+                app.run()
+                return
+            with ContentLibrary(args.library) as library:
+                if args.command == 'add-music':
+                    count = library.add_music_apk(args.apk)
+                    print(f'Added {count} missing music tracks.' if count else 'No missing music tracks to add.')
+                    return
+                library.ensure_builtin_episodes()
+                if args.command == "list":
+                    from .menu import MenuState
+                    state = MenuState(library)
+                    if args.title_language is not None:
+                        state.title_language = args.title_language
+                    for record in library.episodes:
+                        print(f"{record['id'][:12]}  {state.title(record)}  ({record['name']})")
+                    return
+        except (ContentError, SaveError, VMError, OSError) as error:
+            parser.error(str(error))
+
+    elif args.command == "trace":
+        from .trace import trace_archive
+
+        try:
+            result = trace_archive(args.archive, max_steps=args.max_steps, max_events=args.max_events, game=args.game)
+        except (ValueError, OSError) as error:
+            parser.error(str(error))
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        if result["status"] in ("vm_error", "missing_script"):
+            sys.exit(1)
+
+    else:
+        parser.print_help()
+        sys.exit(1)

exp_runtime/decode/__init__.py

@@ -0,0 +1 @@
+"""Lossless KiWi bytecode decoding; EXP archives are handled by content.py."""

exp_runtime/decode/bytecode.py

@@ -0,0 +1,119 @@
+"""Lossless KiWi v2 decoding, verified against libshs09.so FUN_00057068.
+
+This is a binary representation, not a reconstruction of game actions.
+Data words may contain packed text, mutable variables, or other values.
+"""
+from dataclasses import dataclass
+import struct
+
+
+# int32 table at 0x002593a8: only entries equal to 1 consume an operand.
+OPERAND_OPCODES = frozenset({
+    0x01, 0x19, 0x1A, 0x1B, 0x1E, 0x1F, 0x20, 0x23,
+    0x28, 0x29, 0x2A, 0x2B, 0x2C, 0x2D, 0x2E, 0x40, 0x41, 0x5C,
+})
+
+
+class KiwiFormatError(ValueError):
+    """Unsupported or truncated KiWi input, with a file byte offset."""
+
+
+@dataclass(frozen=True)
+class BytecodeInstruction:
+    pc: int
+    byte_offset: int
+    opcode: int
+    operand: int | None
+
+    @property
+    def yield_id(self) -> int | None:
+        if self.opcode == 0x1E:
+            return self.operand
+        if self.opcode == 0x1F:
+            return self.operand >> 8
+        return None
+
+    def branch_target(self) -> int | None:
+        """Statically encoded target in logical instruction indices.
+
+        Native PC arithmetic wraps at 16 bits. Dynamic return opcode 0x43
+        is deliberately not assigned a guessed target.
+        """
+        if self.opcode == 0x29:
+            return self.operand
+        if self.opcode in {0x28, 0x2A, 0x2B, 0x2C, 0x2D, 0x2E}:
+            return (self.pc + self.operand) & 0xFFFF
+        if self.opcode == 0x5C:
+            return (self.pc + (self.operand >> 8)) & 0xFFFF
+        return None
+
+
+@dataclass(frozen=True)
+class KiwiProgram:
+    version: int
+    previous_flag: int
+    previous_data_count: int | None
+    previous_instruction_count: int | None
+    flag: int
+    main_words: tuple[int, ...]
+    gap_count: int
+    extra_words: tuple[int, ...]
+    instructions: tuple[BytecodeInstruction, ...]
+
+    def to_bytes(self) -> bytes:
+        """Re-encode every stored field without interpreting data words."""
+        header = b'kiwi' + bytes((self.version, self.previous_flag))
+        if self.previous_flag:
+            header += struct.pack('>HH', self.previous_data_count,
+                                  self.previous_instruction_count)
+        header += bytes((self.flag,))
+        header += struct.pack('>4H', len(self.main_words), self.gap_count,
+                              len(self.extra_words), len(self.instructions))
+        words = self.main_words + self.extra_words
+        body = struct.pack(f'>{len(words)}H', *words)
+        code = bytearray()
+        for instruction in self.instructions:
+            code.append(instruction.opcode)
+            if instruction.operand is not None:
+                code.extend(struct.pack('>H', instruction.operand))
+        return header + body + code
+
+
+def decode_program(data: bytes) -> KiwiProgram:
+    """Decode v2 strictly; never turn truncated input into invented operands."""
+    pos = 0
+
+    def take(size):
+        nonlocal pos
+        if pos + size > len(data):
+            raise KiwiFormatError(f'truncated KiWi at byte 0x{pos:x}: need {size} bytes')
+        result = data[pos:pos + size]
+        pos += size
+        return result
+
+    def u16():
+        return struct.unpack('>H', take(2))[0]
+
+    if take(4) != b'kiwi':
+        raise KiwiFormatError('invalid KiWi signature at byte 0x0')
+    version = take(1)[0]
+    if version != 2:
+        raise KiwiFormatError(f'unsupported KiWi version {version} at byte 0x4')
+    previous_flag = take(1)[0]
+    previous_data = u16() if previous_flag else None
+    previous_code = u16() if previous_flag else None
+    flag = take(1)[0]
+    main, gap, extra, count = (u16() for _ in range(4))
+    main_words = tuple(u16() for _ in range(main))
+    extra_words = tuple(u16() for _ in range(extra))
+    instructions = []
+    base_pc = previous_code or 0
+    for index in range(count):
+        offset = pos
+        opcode = take(1)[0]
+        operand = u16() if opcode in OPERAND_OPCODES else None
+        instructions.append(BytecodeInstruction(base_pc + index, offset, opcode, operand))
+    if pos != len(data):
+        raise KiwiFormatError(f'{len(data) - pos} trailing bytes at byte 0x{pos:x}')
+    return KiwiProgram(version, previous_flag, previous_data, previous_code,
+                       flag, main_words, gap, extra_words, tuple(instructions))

exp_runtime/exp.py

@@ -0,0 +1,121 @@
+"""Validated EXP containers, independent of game profiles and presentation."""
+from dataclasses import dataclass
+from functools import lru_cache
+import lzma
+import struct
+
+from .decode.bytecode import decode_program
+
+MAX_PAYLOAD = 64 * 1024 * 1024
+
+
+class ContentError(ValueError):
+    """Missing, incompatible, or malformed user content."""
+
+
+@dataclass(frozen=True)
+class Metadata:
+    pack_id: int
+    episode_id: int
+    titles: tuple[str, ...]
+
+    @property
+    def title(self):
+        return self.titles[0]
+
+
+class ExpArchive:
+    """Validated, exact-ID CSPUD reader; native grouped fallback is unsupported."""
+
+    def __init__(self, data: bytes):
+        self.data = data
+        if len(data) < 9 or data[:5] != b'CSPUD':
+            raise ContentError('Not a CSPUD EXP archive')
+        count, = struct.unpack_from('>I', data, 5)
+        index_end = 9 + 6 * count
+        if not count or index_end > len(data):
+            raise ContentError('Invalid EXP index extent')
+        self.entries = {}
+        extents = {}
+        for i in range(count):
+            resource_id, offset = struct.unpack_from('>HI', data, 9 + 6 * i)
+            if resource_id in self.entries:
+                raise ContentError(f'Duplicate EXP resource ID {resource_id}')
+            if offset < index_end or offset + 12 > len(data):
+                raise ContentError(f'Invalid record offset for resource {resource_id}')
+            stored, raw, flags = struct.unpack_from('>III', data, offset)
+            end = offset + 12 + stored
+            if end > len(data) or raw > MAX_PAYLOAD or stored > MAX_PAYLOAD:
+                raise ContentError(f'Invalid record size for resource {resource_id}')
+            if flags & ~1:
+                raise ContentError(f'Unsupported EXP flags 0x{flags:x}')
+            if not flags & 1 and stored != raw:
+                raise ContentError('Literal EXP record has conflicting sizes')
+            self.entries[resource_id] = offset
+            extents[offset] = end
+        last_end = index_end
+        for start, end in sorted(extents.items()):
+            if start < last_end:
+                raise ContentError('Partially overlapping EXP records')
+            last_end = end
+
+    @lru_cache(maxsize=32)
+    def read(self, resource_id: int) -> bytes:
+        try:
+            offset = self.entries[resource_id]
+        except KeyError:
+            raise ContentError(f'EXP resource {resource_id} is absent; grouped lookup is unsupported') from None
+        stored, raw, flags = struct.unpack_from('>III', self.data, offset)
+        payload = self.data[offset + 12:offset + 12 + stored]
+        if not flags & 1:
+            return payload
+        if len(payload) < 13:
+            raise ContentError('Truncated EXP LZMA wrapper')
+        prop, dictionary, size1, size2 = struct.unpack_from('<BIII', payload)
+        if prop >= 225 or dictionary > MAX_PAYLOAD or size1 != raw or size2 != raw:
+            raise ContentError('Inconsistent or unsupported EXP LZMA header')
+        try:
+            # EXP supplies the output boundary; native streams need no end
+            # marker. Raw decoding also avoids older liblzma versions rejecting
+            # a known-size Alone header when an encoder includes an end marker.
+            decoder = lzma.LZMADecompressor(format=lzma.FORMAT_RAW, filters=[dict(
+                id=lzma.FILTER_LZMA1, dict_size=max(4096, dictionary),
+                lc=prop % 9, lp=(prop // 9) % 5, pb=prop // 45)])
+            result = decoder.decompress(payload[13:], max_length=raw)
+        except lzma.LZMAError as error:
+            raise ContentError(f'Invalid EXP LZMA stream: {error}') from error
+        if len(result) != raw:
+            raise ContentError('Truncated or oversized decoded EXP payload')
+        return result
+
+    def metadata(self) -> Metadata:
+        data = self.read(1)
+        if len(data) < 4:
+            raise ContentError('Truncated episode metadata')
+        pack, episode = struct.unpack_from('>HH', data)
+        pos, titles = 4, []
+        try:
+            for _ in range(5):
+                length, = struct.unpack_from('>H', data, pos)
+                pos += 2
+                if pos + length > len(data):
+                    raise ContentError('Truncated localized title')
+                titles.append(data[pos:pos + length].decode('utf-8'))
+                pos += length
+        except (struct.error, UnicodeError) as error:
+            raise ContentError('Invalid localized episode metadata') from error
+        if pos != len(data):
+            raise ContentError('Unsupported trailing episode metadata')
+        return Metadata(pack, episode, tuple(titles))
+
+    def programs(self):
+        programs = {}
+        for resource_id in self.entries:
+            data = self.read(resource_id)
+            if data.startswith(b'kiwi'):
+                try:
+                    programs[resource_id] = decode_program(data)
+                except ValueError as error:
+                    raise ContentError(f'Invalid KiWi resource {resource_id}: {error}') from error
+        return programs
+