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)

$ pip install make_playlist

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):

    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
    

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:

# Find multimedia files whose names start with a-f
playlist = make_playlist(
    '/Music/collections',
    ('mp3', 'mp4', 'aac'),
    pattern='^[a-f].*',
    recursive=True,
    unique=True
)

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

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:

help(make_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

Treeware

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

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!