{"id":20326061,"url":"https://github.com/matteoguadrini/mkpl","last_synced_at":"2026-01-29T16:01:19.333Z","repository":{"id":58922394,"uuid":"528384146","full_name":"MatteoGuadrini/mkpl","owner":"MatteoGuadrini","description":"Make M3U format playlist from command line","archived":false,"fork":false,"pushed_at":"2025-12-31T09:38:20.000Z","size":244,"stargazers_count":50,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-04T13:44:31.253Z","etag":null,"topics":["make","maker","makers","music-generation","music-library","playlist","playlist-continuation","playlist-generator","playlist-maker","playlist-manager","python"],"latest_commit_sha":null,"homepage":"https://matteoguadrini.github.io/mkpl","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatteoGuadrini.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-24T11:01:54.000Z","updated_at":"2025-12-31T09:38:14.000Z","dependencies_parsed_at":"2025-12-01T04:01:48.921Z","dependency_job_id":null,"html_url":"https://github.com/MatteoGuadrini/mkpl","commit_stats":{"total_commits":88,"total_committers":1,"mean_commits":88.0,"dds":0.0,"last_synced_commit":"676cb478938af860b0630e14854872cfcf0758c8"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/MatteoGuadrini/mkpl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fmkpl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fmkpl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fmkpl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fmkpl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatteoGuadrini","download_url":"https://codeload.github.com/MatteoGuadrini/mkpl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fmkpl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28880838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["make","maker","makers","music-generation","music-library","playlist","playlist-continuation","playlist-generator","playlist-maker","playlist-manager","python"],"created_at":"2024-11-14T19:42:47.455Z","updated_at":"2026-01-29T16:01:19.328Z","avatar_url":"https://github.com/MatteoGuadrini.png","language":"Python","funding_links":["https://www.paypal.me/guos"],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"img/mkpl_logo.svg\" alt=\"mkpl\" title=\"mkpl\" align=\"right\" width=\"150\"/\u003e **make_playlist**: Playlist maker\n======\n\n``mkpl`` is a _command line tool_ to create playlist files (**[M3U](https://en.wikipedia.org/wiki/M3U) format**), automatically.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Command Arguments](#command-arguments)\n- [Examples](#examples)\n- [Python Module Usage](#use-it-like-python-module)\n- [Contributing](#open-source)\n- [License \u0026 Acknowledgments](#acknowledgments)\n\n## Installation\n\nTo install ``mkpl``, choose one of the following methods:\n\n### Option 1: PyPI Installation (Recommended)\n\n```console\n$ pip install make_playlist\n```\n\n### Option 2: From Source\n\n```console\n$ git clone https://github.com/MatteoGuadrini/mkpl.git\n$ cd mkpl\n$ pip install .\n```\n\n## Command Arguments\n\n``mkpl`` supports numerous command-line arguments for flexible playlist creation. Below is a comprehensive reference:\n\n### Basic Options\n\n| Short | Long | Description | Arguments |\n|-------|------|-------------|-----------|\n| -d | --directories | Directories containing multimedia files | Path of directories |\n| -e | --exclude-dirs | Exclude specific directory paths | Path of directories |\n| -r | --recursive | Recursively search directories | — |\n\n### File Format Options\n\n| Short | Long | Description | Arguments |\n|-------|------|-------------|-----------|\n| -f | --format | Select only a specific file format | Format (e.g., mp3, mkv) |\n| -i | --include | Include additional file formats | Format list (e.g., mp3 mp4) |\n| -p | --pattern | Include files matching regex pattern | Regular expression |\n| -P | --exclude-pattern | Exclude files matching regex pattern | Regular expression |\n\n### File Size \u0026 Duration Filters\n\n| Short | Long | Description | Arguments |\n|-------|------|-------------|-----------|\n| -z | --size | Minimum file size | Bytes, kb, mb, gb (e.g., 2mb) |\n| -A | --max-size | Maximum file size | Bytes, kb, mb, gb (e.g., 4mb) |\n| -M | --length | Minimum track length | Seconds |\n| -X | --max-length | Maximum track length | Seconds |\n\n### Playlist Configuration\n\n| Short | Long | Description | Arguments |\n|-------|------|-------------|-----------|\n| -t | --title | Set playlist title | Title string |\n| -g | --encoding | Set text encoding | UTF-8, ASCII, UNICODE |\n| -I | --image | Set playlist cover image | Image file path |\n| -m | --max-tracks | Limit number of tracks | Number |\n\n### File Management\n\n| Short | Long | Description | Arguments |\n|-------|------|-------------|-----------|\n| -F | --file | Add additional files | File paths |\n| -l | --link | Add remote file links | HTTP/HTTPS URLs |\n| -j | --join | Join other playlist files | Playlist file paths |\n| -k | --other-playlists | Include other playlists | Playlist file paths |\n\n### Sorting \u0026 Ordering\n\n| Short | Long | Description |\n|-------|------|-------------|\n| -o | --orderby-name | Sort by filename |\n| -O | --orderby-date | Sort by creation date |\n| -T | --orderby-track | Sort by track number |\n| -y | --orderby-year | Sort by year metadata |\n| -Z | --orderby-size | Sort by file size |\n| -L | --orderby-length | Sort by track duration |\n| -s | --shuffle | Randomize track order |\n| -D | --descending | Reverse sort order |\n\n### Output \u0026 Processing\n\n| Short | Long | Description |\n|-------|------|-------------|\n| -a | --absolute | Use absolute file paths |\n| -u | --unique | Remove duplicate files |\n| -c | --append | Append to existing playlist |\n| -w | --windows | Use Windows path separators |\n| -x | --unix | Use Unix path separators |\n| -U | --url-chars | Apply URL encoding to paths |\n| -N | --add-info | Include file metadata (#EXTINF) |\n\n### Interactive \u0026 Utility Options\n\n| Short | Long | Description |\n|-------|------|-------------|\n| -R | --interactive | Confirm each file before adding |\n| -C | --count | Count files without creating playlist |\n| -S | --split | Split into separate playlists by directory |\n| -Y | --filter | Filter by metadata (artist, album, etc.) |\n| -n | --cache | Cache results (seconds) |\n| -v | --verbose | Enable debug output |\n| -E | --explain-error | Show detailed error traceback |\n| -V | --version | Display version information |\n\n## Examples\n\n### Basic Usage\n\n1. **Create a playlist for one music album:**\n\n    ```bash\n    cd myalbum\n    mkpl myalbum.m3u\n    # or use default naming\n    mkpl\n    ```\n\n### Directory \u0026 Format Filtering\n\n2. **Create playlist from specific format:**\n\n    ```bash\n    mkpl -d HarryPotter -f mkv HP_saga.m3u\n    ```\n\n3. **Create shuffled playlist with size filters:**\n\n    ```bash\n    mkpl -d \"my_mp3_collection\" \"my_mp4_collection\" -rs -z 2mb -A 4mb \"my music.m3u\"\n    ```\n\n4. **Exclude specific directories:**\n\n    ```bash\n    mkpl -d \"my_mp3_collection\" \"my_mp4_collection\" -r -s -e \"my_mp3_collection/metallica\" \"my_mp3_collection/dk\" -- \"my music.m3u\"\n    ```\n\n### Advanced Filtering\n\n5. **Limit by track count:**\n\n    ```bash\n    mkpl -d \"my_series/GOT\" -m 15 \"got_first_15.m3u\"\n    ```\n\n6. **Filter by track number with regex:**\n\n    ```bash\n    mkpl -d \"my_mp3_collection\" -r -p \"^[12]|[012]{2}\" \"my music.m3u\"\n    ```\n\n7. **Filter by duration range:**\n\n    ```bash\n    mkpl -d \"music_collection\" -M 42 -X 300 \"My new collection\"\n    ```\n\n### File Management\n\n8. **Add external files to playlist:**\n\n    ```bash\n    cd myalbum_special\n    mkpl myalbum_special.m3u -F music_video.mp4 other_stuff/song1.mp3 other_stuff/song2.mp3\n    ```\n\n9. **Add remote file links:**\n\n    ```bash\n    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\n    ```\n\n10. **Merge playlists:**\n\n    ```bash\n    mkpl -d \"Rock'n'Roll\" -- \"RockNRoll.m3u\"\n    mkpl -d \"Hard Rock\" -j \"RockNRoll.m3u\" -- \"Rock.m3u\"\n    ```\n\n### Metadata \u0026 Formatting\n\n11. **Add playlist metadata:**\n\n    ```bash\n    mkpl -d \"new_collection\" -r \"my music.m3u\" -t \"My Collection\" -g \"UTF-8\" -I \"new_collection/cover.jpg\"\n    ```\n\n12. **Include track information (#EXTINF):**\n\n    ```bash\n    mkpl -d \"HeavyMetal/Master of Puppets\" -N \"master\"\n    cat \"master.m3u\"\n    #EXTM3U\n    #EXTINF:516,Metallica - Master of Puppets\n    HeavyMetal/Master Of Puppets/02 - Master Of Puppets.mp3\n    ```\n\n### Sorting \u0026 Organization\n\n13. **Sort by various criteria:**\n\n    ```bash\n    mkpl -d \"new_collection\" -r \"my music.m3u\" -o        # by name\n    mkpl -d \"new_collection\" -r \"my music.m3u\" -O        # by date\n    mkpl -d \"new_collection\" -r \"my music.m3u\" -T        # by track\n    mkpl -d \"new_collection\" -r \"my music.m3u\" -y        # by year\n    mkpl -d \"new_collection\" -r \"my music.m3u\" -Z        # by size\n    mkpl -d \"new_collection\" -r \"my music.m3u\" -L -D     # by length (descending)\n    ```\n\n14. **Split into multiple playlists:**\n\n    ```bash\n    mkpl -d \"folder1\" \"folder2\" \"folder3\" -r \"my_music.m3u\" -S\n    # Results in: my_music.m3u, folder1.m3u, folder2.m3u, folder3.m3u\n    ```\n\n### Metadata Filtering\n\n15. **Filter by artist and album:**\n\n    ```bash\n    mkpl -d \"HeavyMetal\" -Y artist=Metallica -Y album=\"Master of Puppets\" -- \"MoP.m3u\"\n    ```\n\n### Interactive \u0026 Utility Operations\n\n16. **Count files:**\n\n    ```bash\n    mkpl -d \"new_collection\" -r -C\n    # Output: 4023\n    ```\n\n17. **Interactive confirmation for each file:**\n\n    ```bash\n    mkpl -d \"new_collection\" -r -R\n    Add file new_collection/sample1.mp3 to playlist? [Y/n]: y\n    ```\n\n18. **Append to existing playlist without duplicates:**\n\n    ```bash\n    mkpl -d \"new_collection\" -rsu \"my music.m3u\" -a\n    ```\n\n## Use it like Python module\n\nYou can use `mkpl` programmatically in your Python projects to build and write playlists dynamically.\n\n### Quick Start\n\nImport the main functions:\n\n```python\nfrom make_playlist import make_playlist, write_playlist\n```\n\nBasic example — create and write a playlist:\n\n```python\n# Find multimedia files whose names start with a-f\nplaylist = make_playlist(\n    '/Music/collections',\n    ('mp3', 'mp4', 'aac'),\n    pattern='^[a-f].*',\n    recursive=True,\n    unique=True\n)\n\nwrite_playlist('/Music/AtoF.m3u', 'wt', playlist)\n```\n\n### Important Notes\n\n- `make_playlist()` returns a `Playlist` object containing `PlaylistEntry` items\n- You can iterate, filter, or convert results to a list before writing\n- Most CLI flags are exposed as keyword arguments (e.g., `recursive`, `unique`, `add_info`, `encoding`, `title`, `image`)\n- Use `encoding='utf-8'` parameter for UTF-8 encoded output\n- `pathlib.Path` objects are fully supported\n\n### Python Examples\n\n**Example 1: Write UTF-8 playlist with metadata**\n\n```python\nfrom pathlib import Path\n\nplist = make_playlist(\n    Path('/Music/collections'),\n    ('mp3',),\n    recursive=True\n)\n\nwrite_playlist(\n    Path('/Music/AtoF.m3u'),\n    'wt',\n    plist,\n    encoding='utf-8',\n    title='A–F Collection',\n    image=Path('/Music/cover.jpg')\n)\n```\n\n**Example 2: Inspect and filter results**\n\n```python\nresults = make_playlist(\n    '/Music/collections',\n    ('mp3', 'flac'),\n    recursive=True\n)\n\nfor entry in results:\n    print(f\"File: {entry.file}\")\n    if entry.extinf:\n        print(f\"Info: {entry.extinf}\")\n```\n\n**Example 3: Advanced filtering with metadata**\n\n```python\nplaylist = make_playlist(\n    '/Music/HeavyMetal',\n    ('mp3',),\n    recursive=True,\n    filters=[\n        ('artist', 'Metallica'),\n        ('album', 'Master of Puppets')\n    ],\n    add_info=True\n)\n\nwrite_playlist('/Music/MoP.m3u', 'wt', playlist)\n```\n\n### API Reference\n\nSee function docstrings for complete parameter documentation:\n\n```python\nhelp(make_playlist)\nhelp(write_playlist)\n```\n   \n## Open source\n_mkpl_ is an open source project. Any contribute, It's welcome.\n\n**A great thanks**.\n\nFor donations, press this\n\nFor me\n\n[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.me/guos)\n\nFor [Telethon](http://www.telethon.it/)\n\nThe Telethon Foundation is a non-profit organization recognized by the Ministry of University and Scientific and Technological Research.\nThey were born in 1990 to respond to the appeal of patients suffering from rare diseases.\nCome today, we are organized to dare to listen to them and answers, every day of the year.\n\n[Adopt the future](https://www.ioadottoilfuturo.it/)\n\n\n## Treeware  \n\nThis package is [Treeware](https://treeware.earth). If you use it in production, \nthen we ask that you [**buy the world a tree**](https://plant.treeware.earth/matteoguadrini/mkpl) to thank us for our work. \nBy contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.\n\n[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen?style=for-the-badge)](https://plant.treeware.earth/MatteoGuadrini/mkpl)\n\n\n## Acknowledgments\n\nSpecial thanks to:\n\n- **Mark Lutz** — _Learning Python_ and _Programming Python_ books\n- **Kenneth Reitz \u0026 Tanya Schlusser** — _The Hitchhiker's Guide to Python_\n- **Dane Hillard** — _Practices of the Python Pro_\n- **My family** — For continuous support and inspiration\n\nThanks, Python!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatteoguadrini%2Fmkpl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatteoguadrini%2Fmkpl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatteoguadrini%2Fmkpl/lists"}