LibRay/AGENTS.md

LibRay — Agent Quick Reference

Important

Make sure to use the virtual environment in .venv and not global pip.

Repo

• Python 3 CLI tool for decrypting/encrypting/examining PS3 Blu-Ray ISOs
• Entry point: libray/libray (also libray/libray.py, identical copy)
• Package: libray/ — modules: core.py (main logic), iso.py (ISO parsing), ird.py (IRD parsing), sfo.py (PARAM.SFO)
• Tests: tests/ — test_iso.py, test_interface.py (interface test is currently skipped/broken)
• Tools: tools/keys2db.py (builds libray/data/keys.db from redump keys), tools/rpcs3.py (fetches compat data)

Commands

• Install deps: pip install -r requirements.txt
• Run tests: python -m unittest discover -b
• Build sdist + wheel: python3 setup.py sdist bdist_wheel
• Publish: twine upload dist/*

Parallelization

• Decrypt and re-encrypt support multi-threading via -p/--threads CLI argument
• Default: auto-detects CPU core count via os.cpu_count()
• Each sector is independently decrypted (per-sector IV in AES-CBC), making it embarrassingly parallel
• Uses concurrent.futures.ThreadPoolExecutor (threads, not processes, since pycryptodome releases the GIL)
• Unencrypted regions are always copied sequentially (no crypto needed)
• Sector data is read upfront into memory, then processed in parallel, then written in order

Gotchas

• Crypto package conflict: pycrypto/crypto will break pycryptodome. If ImportError: No module named Crypto.Cipher, run:

  pip uninstall crypto pycrypto && pip install pycryptodome
  

• keys.db is generated, not committed. Build it with python3 tools/keys2db.py (requires keys in tools/keys/). It's listed in .gitignore via libray/data/*.db.
• libray/__init__.py dynamically imports all submodules via pkgutil.walk_packages — don't expect explicit imports.
• test_interface.py is skipped (@unittest.skip('currently broken')) — the interface test won't run.
• .editorconfig enforces 4-space indent for .py, 2-space for .yml/.yaml.
• No linting/typechecking config exists — plain unittest, no pytest, no pre-commit.