make_playlist: Playlist maker

mkpl is a command line tool to create playlist files (M3U format), automatically.

Table of Contents

• Installation
• Command Arguments
• Examples
• Python Module Usage
• Contributing
• License & Acknowledgments

Installation

To install mkpl, choose one of the following methods:

Option 1: PyPI Installation (Recommended)

To install with pip:

# Install make_playlist package (deprecated)
pip install make_playlist
# Use user-space
pip install --user make_playlist

Use external tools like pipx and/or uv (they create virtual environments for you); upgrading is done via a specific subcommand

pipx install make_playlist && pipx upgrade-all || uv pip install make_playlist --upgrade

Deactivate the externally managed file, temporarily or permanently

pip install make_playlist --break-system-packages || python3 -m pip config set global.break-system-packages true

Option 2: From Source

$ git clone https://github.com/MatteoGuadrini/mkpl.git
$ cd mkpl
$ pip install .

Command Arguments

mkpl supports numerous command-line arguments for flexible playlist creation. Below is a comprehensive reference:

Basic Options

File Format Options

File Size, BPM & Duration Filters

Playlist Configuration

File Management

Sorting & Ordering

Output & Processing

Interactive & Utility Options

Examples

Basic Usage

1. Create a playlist for one music album:

   cd myalbum
   mkpl myalbum.m3u
   # or use default naming
   mkpl
   

Directory & Format Filtering

2. Create playlist from specific format:

   mkpl -d HarryPotter -f mkv HP_saga.m3u
   

3. Create shuffled playlist with size filters:

   mkpl -d "my_mp3_collection" "my_mp4_collection" -rs -z 2mb -A 4mb "my music.m3u"
   

4. Exclude specific directories:

   mkpl -d "my_mp3_collection" "my_mp4_collection" -r -s -e "my_mp3_collection/metallica" "my_mp3_collection/dk" -- "my music.m3u"
   

Advanced Filtering

5. Limit by track count:

   mkpl -d "my_series/GOT" -m 15 "got_first_15.m3u"
   

6. Filter by track number with regex:

   mkpl -d "my_mp3_collection" -r -p "^[12]|[012]{2}" "my music.m3u"
   

7. Filter by duration range:

   mkpl -d "music_collection" -M 42 -X 300 "My new collection"
   

8. Filter by BPM range:

   mkpl -d "music_collection" -r -b 120 -B 140 "upbeat_tracks.m3u"
   

File Management

9. Add external files to playlist:

   cd myalbum_special
   mkpl myalbum_special.m3u -F music_video.mp4 other_stuff/song1.mp3 other_stuff/song2.mp3
   

10. Add remote file links:

    mkpl -d "new_collection" -r "my music.m3u" -l http://192.168.1.123/mp3/song1.mp3 http://192.168.1.123/mp3/song2.mp4
    

11. Merge playlists:

    mkpl -d "Rock'n'Roll" -- "RockNRoll.m3u"
    mkpl -d "Hard Rock" -j "RockNRoll.m3u" -- "Rock.m3u"
    

Metadata & Formatting

12. Add playlist metadata:

    mkpl -d "new_collection" -r "my music.m3u" -t "My Collection" -g "UTF-8" -I "new_collection/cover.jpg"
    

13. Include track information (#EXTINF), automatically or interactive:

    mkpl -d "HeavyMetal/Master of Puppets" -N "master"
    cat "master.m3u"
    #EXTM3U
    #EXTINF:516,Metallica - Master of Puppets
    HeavyMetal/Master Of Puppets/02 - Master Of Puppets.mp3
    

    mkpl -d "HeavyMetal/Master of Puppets" -NK "master"
    File: HeavyMetal/Master Of Puppets/02 - Master Of Puppets.mp3
    Enter artist name []: Metallica
    Enter title name: Master of Puppets
    File: HeavyMetal/Master Of Puppets/01 - Battery.mp3
    Enter artist name [Metallica]: 
    Enter title name: Battery
    File: HeavyMetal/Master Of Puppets/03 - The Thing That Should Not Be.mp3
    cat "master.m3u"
    #EXTM3U
    #EXTINF:516,Metallica - Master of Puppets
    HeavyMetal/Master Of Puppets/02 - Master Of Puppets.mp3
    

Sorting & Organization

14. Sort by various criteria:

    mkpl -d "new_collection" -r "my music.m3u" -o        # by name
    mkpl -d "new_collection" -r "my music.m3u" -O        # by date
    mkpl -d "new_collection" -r "my music.m3u" -T        # by track
    mkpl -d "new_collection" -r "my music.m3u" -y        # by year
    mkpl -d "new_collection" -r "my music.m3u" -Z        # by size
    mkpl -d "new_collection" -r "my music.m3u" -G        # by bpm
    mkpl -d "new_collection" -r "my music.m3u" -H        # by publisher
    mkpl -d "new_collection" -r "my music.m3u" -L -D     # by length (descending)
    

15. Split into multiple playlists:

    mkpl -d "folder1" "folder2" "folder3" -r "my_music.m3u" -S
    # Results in: my_music.m3u, folder1.m3u, folder2.m3u, folder3.m3u
    

Metadata Filtering

16. Filter by artist and album:

    mkpl -d "HeavyMetal" -Y artist=Metallica -Y album="Master of Puppets" -- "MoP.m3u"
    

Interactive & Utility Operations

17. Count files:

    mkpl -d "new_collection" -r -C
    # Output: 4023
    

18. Interactive confirmation for each file:

    mkpl -d "new_collection" -r -R
    Add file new_collection/sample1.mp3 to playlist? [Y/n]: y
    

19. Append to existing playlist without duplicates:

    mkpl -d "new_collection" -rsu "my music.m3u" -a
    

20. Speed process with cache:

    mkpl -d "new_collection" -r -n 300 "my music.m3u" -a # for 5 minutes read the cache if playlist is same
    

List of filter tags

Use it like Python module

You can use mkpl programmatically in your Python projects to build and write playlists dynamically.

Quick Start

Import the main functions:

from make_playlist import make_playlist, write_playlist

Basic example — create and write a playlist:

from make_playlist import make_playlist, write_playlist, sort_playlist

# Generate playlist
playlist = make_playlist(
    directories=["/path/to/music"],
    extensions=["mp3", "flac"],
    recursive=True,
    filters=[("artist", "Metallica")],
    add_info=True
)

# Sort playlist
sort_playlist(playlist, sortby_name=True)

# Write to file
write_playlist(
    "output.m3u",
    "wt",
    playlist,
    title="Metallica Collection",
    encoding="utf-8"
)

Important Notes

• make_playlist() returns a Playlist object containing PlaylistEntry items
• You can iterate, filter, or convert results to a list before writing
• Most CLI flags are exposed as keyword arguments (e.g., recursive, unique, add_info, encoding, title, image)
• Use encoding='utf-8' parameter for UTF-8 encoded output
• pathlib.Path objects are fully supported

Python Examples

Example 1: Write UTF-8 playlist with metadata

from pathlib import Path

plist = make_playlist(
    Path('/Music/collections'),
    ('mp3',),
    recursive=True
)

write_playlist(
    Path('/Music/AtoF.m3u'),
    'wt',
    plist,
    encoding='utf-8',
    title='A–F Collection',
    image=Path('/Music/cover.jpg')
)

Example 2: Inspect and filter results

results = make_playlist(
    '/Music/collections',
    ('mp3', 'flac'),
    recursive=True
)

for entry in results:
    print(f"File: {entry.file}")
    if entry.extinf:
        print(f"Info: {entry.extinf}")

Example 3: Advanced filtering with metadata

playlist = make_playlist(
    '/Music/HeavyMetal',
    ('mp3',),
    recursive=True,
    filters=[
        ('artist', 'Metallica'),
        ('album', 'Master of Puppets')
    ],
    add_info=True
)

write_playlist('/Music/MoP.m3u', 'wt', playlist)

API Reference

See function docstrings for complete parameter documentation:

from make_playlist import make_playlist, write_playlist, sort_playlist

help(make_playlist)
help(sort_playlist)
help(write_playlist)

Open source

mkpl is an open source project. Any contribute, It's welcome.

A great thanks.

For donations, press this

For me

For Telethon

The Telethon Foundation is a non-profit organization recognized by the Ministry of University and Scientific and Technological Research. They were born in 1990 to respond to the appeal of patients suffering from rare diseases. Come today, we are organized to dare to listen to them and answers, every day of the year.

Adopt the future

Acknowledgments

Special thanks to:

• Mark Lutz — Learning Python and Programming Python books
• Kenneth Reitz & Tanya Schlusser — The Hitchhiker's Guide to Python
• Dane Hillard — Practices of the Python Pro
• My family — For continuous support and inspiration

Thanks, Python!