music-playlist-format 0.1.0

Music Playlist (MPL) format handler

MPL – Music Playlist Format

A minimal, human‑readable playlist format designed for local music players.
MPL stores absolute file paths and partial file hashes, so tracks can be found even after they've been moved or renamed.

Format

{
    "format": "mpl/1.0",
    "playlist_name": "My Mix",
    "tracks": [
        {
            "path": "~/Music/Artist/Album/track1.flac",
            "hash": "abcd123..."
        },
        {
            "path": "~/Downloads/song2.mp3",
            "hash": "abcd123..."
        }
    ]
}

• path – absolute, UTF‑8 encoded file location
• hash – sha256:<hexdigest> of the first 1 MB + last 1 MB + file size
• format – always mpl/1.0 for this version

Installation

pip install mpl

Usage

Create a playlist

from mpl import create_playlist

tracks = [
    "/home/user/Music/song1.flac",
    "/home/user/Music/song2.mp3",
]

path = create_playlist(
    output_path="my_playlist.mpl",
    file_list=tracks,
    playlist_name="My Mix",
)
print(f"Playlist saved to {path}")

Load a playlist

from mpl import load_playlist

files = load_playlist("my_playlist.mpl")
for f in files:
    print(f)

Repair broken paths

If you've moved your music collection, repair_playlist scans one or more directories, matches files by their hash, and updates the .mpl file.

from mpl import repair_playlist

fixed = repair_playlist(
    "my_playlist.mpl",
    search_dirs=["~/Music", "/media/external"],
)
print(f"Fixed {fixed} missing tracks.")

Advanced: message callbacks

All functions accept an optional msg_callback(level, message) (info and warning levels). This lets you integrate with your own logging or UI without relying on stderr.

def my_logger(level, msg):
    if level == "warning":
        print(f"Warning: {msg}")

load_playlist("playlist.mpl", msg_callback=my_logger)

File structure

mpl/
├── __init__.py     # public API
├── core.py         # create_playlist, load_playlist, repair_playlist
└── helpers.py      # supported audio formats, hash generation, path validation