smart-playlist-io

Build and inspect Apple Music smart playlists from Python.

from smart_playlist_io import AND, OR, rule, encode_b64

rules = AND([
    rule("Rating", "greater", 3),
    rule("LastPlayed", "not_in_last", 6, "months"),
    OR([
        rule("Genre", "starts", "Ambient"),
        rule("Genre", "starts", "Electronic / Ambient"),
    ]),
])

info_b64, criteria_b64 = encode_b64(rules, limit=25, select_by="most_played")

Produces the Smart Info and Smart Criteria base64 blobs used in Music.app's Library XML format. Import them via File > Library > Import Playlist or the AppleScript add command. Also decodes existing smart playlists back to readable rules.

Not affiliated with or endorsed by Apple Inc.

Install

Requires Python 3.12+.

pip install smart-playlist-io

Encode

from smart_playlist_io import AND, OR, rule, encode, encode_b64

# Raw bytes
info_bytes, criteria_bytes = encode(rules, limit=25, select_by="most_played", live=True)

# Base64 strings (for XML plist)
info_b64, criteria_b64 = encode_b64(rules, limit=25, select_by="most_played")

Options

Fields and operators

Decode

from smart_playlist_io import decode_criteria, decode_info_flags

rules = decode_criteria(criteria_bytes)   # ['AND', 'Rating > 3', ...]
flags = decode_info_flags(info_bytes)     # 'live updating, limit 25 items, most played'

CLI

Decode all smart playlists in a Library XML export:

decode-smart-playlists /path/to/Library.xml
decode-smart-playlists /path/to/Library.xml --out baseline.md

Known Limitations

• String fields (Name, Artist, Album, Genre, etc.) are limited to 127 characters due to a UTF-16 byte-length constraint in the binary format. Longer values raise ValueError.
• The binary format is reverse-engineered from 2021 Music.app library exports and may change with future macOS updates. If imports start failing after an OS update, see docs/runbook-format-changes.md.
• Decoding is best-effort: unknown field IDs and operator codes are reported as hex literals rather than raising errors.

Notes

Binary format details and the skip-length padding decision are in docs/format-constants.md. Architecture decisions behind the boilerplate structure and top-level OR handling are documented in docs/adr-001-boilerplate-n2-no-identity-child.md and docs/adr-002-top-level-or-emitted-directly.md.

Format knowledge derived from itunessmart by cvzi and banshee-itunes-import-plugin by Scott Peterson. See NOTICE for license text.

License

MIT