Project: M3Unator - Web Directory Playlist Creator
Version: 1.1.0
Author: Hasan Beder
License: GPL-3.0-or-later
GitHub: https://github.com/hasanbeder/M3Unator

M3Unator is a browser userscript that creates .m3u and UTF-8 .m3u8 playlists from web directory listings. It detects media files, optionally scans subdirectories, and exports playlist files that can be opened in common media players and IPTV-compatible applications.

The script runs locally in the browser through a userscript manager. It reads directory listing pages, collects media URLs, and writes those URLs into a playlist file. It does not upload scanned links or generated playlists to a remote service.

1. Overview
2. Installation
3. Quick Start
4. User Interface
5. Playlist Output
6. IPTV Group Title
7. Directory Scanning
8. Supported Directory Listings
9. Supported Media Formats
10. Performance And Limits
11. Privacy And Security
12. Troubleshooting
13. Technical Notes
14. Maintenance Checklist

M3Unator is designed for public or accessible web server indexes such as Apache autoindex, Nginx autoindex, LiteSpeed listings, Lighttpd listings, IIS directory browsing, and Caddy browse pages.

When a page looks like a supported directory listing, M3Unator adds a small launcher button. From the popup, the user can choose media types, scan depth, output format, optional IPTV category behavior, and then download the generated playlist.

Main use cases:

• Create a video playlist from a single directory.
• Create an audio playlist from a music archive.
• Recursively scan nested folders and keep readable playlist titles.
• Export UTF-8 .m3u8 playlists for HLS/IPTV-oriented workflows.
• Add optional IPTV group-title metadata without breaking standard M3U output.

Install a userscript manager first:

• Tampermonkey: https://www.tampermonkey.net/
• Violentmonkey: https://violentmonkey.github.io/

Install M3Unator from one of these sources:

• Greasy Fork: https://greasyfork.org/en/scripts/521593-m3unator-web-directory-playlist-creator
• OpenUserJS: https://openuserjs.org/scripts/hasanbeder/M3Unator_-_Web_Directory_Playlist_Creator
• GitHub raw userscript: https://raw.githubusercontent.com/hasanbeder/M3Unator/main/M3Unator.user.js

For Tampermonkey v5.0 and newer, browser extension developer mode may need to be enabled before userscripts can run.

1. Open a supported web directory listing.
2. Click the M3Unator launcher in the top-right corner.
3. Enter a playlist name.
4. Choose .m3u or .m3u8.
5. Select Video, Audio, or both.
6. Choose current-directory scanning or custom recursive depth.
7. Optionally configure IPTV group-title.
8. Click Create Playlist.
9. Download the generated playlist when scanning finishes.

The current interface is a compact dark popup with these main controls:

• Playlist name: File name used for the downloaded playlist.
• Format selector: Switches between .m3u and .m3u8.
• Group title button: Opens the optional IPTV Group Title field.
• Group Title field: Empty means no group-title; typed text applies a manual category.
• Folder button inside Group Title: Toggles First folder category mode.
• Video toggle: Includes supported video files.
• Audio toggle: Includes supported audio files.
• Subfolder/depth controls: Select current directory or recursive scanning depth.
• Fast scan switch: Enables more aggressive concurrent scanning for trusted servers.
• Create Playlist: Starts scanning and playlist generation.
• Pause, Resume, Cancel: Controls an active scan.
• Stats bar: Shows total files, video files, audio files, folders, depth, and errors.
• Recent Activity: Shows categorized scan and export log entries.
• About dialog: Shows version and feature summary.

M3Unator exports Extended M3U style playlists.

Standard entry:

#EXTINF:-1,Folder/Movie.mp4
https://example.com/media/Folder/Movie.mp4

IPTV category entry:

#EXTINF:-1 group-title="Movies",Movie.mp4
https://example.com/media/Movies/Movie.mp4

Use .m3u for general media players. It is a plain Extended M3U playlist.

Use .m3u8 for UTF-8, HLS, and IPTV-oriented workflows. M3Unator includes a UTF-8 BOM because some older IPTV devices and players handle non-ASCII names more reliably with it.

group-title is optional metadata used by many IPTV players to group entries into categories.

M3Unator supports three practical modes:

Leave Group Title empty.

Output stays classic:

#EXTINF:-1,Title

This is the safest mode for normal media players and preserves the old playlist behavior.

Type a value in the Group Title field.

All entries receive the same category:

#EXTINF:-1 group-title="My Category",Title

Use this when the scanned directory has a single clear category.

Click the folder button inside the Group Title field.

M3Unator uses the first folder segment as the IPTV category and removes that first folder from the visible title so the category is not repeated.

Example input titles:

Movies/Action/Movie A.mp4
Movies/Drama/Movie B.mp4
Clips/Short.mp4
RootVideo.mp4

With playlist name My Playlist, First folder mode exports the categories like this:

Movies -> Action/Movie A.mp4
Movies -> Drama/Movie B.mp4
Clips  -> Short.mp4
My Playlist -> RootVideo.mp4

Root-level files use the playlist name as their group-title. Long automatically generated group titles are capped to keep player category lists readable.

M3Unator scans the current directory page and can optionally follow subdirectories.

Scanning behavior:

• Uses browser fetch requests to read directory listing pages.
• Parses links from the returned HTML.
• Detects media files by extension.
• Resolves relative links with the page URL as base.
• Tracks visited directory URLs to avoid repeated scans.
• Skips recursive fetches when a linked HTML page is not recognized as a directory listing.
• Processes large file lists in batches so the UI remains responsive.
• Prevents duplicate playlist entries when repeated URLs appear across batches.

Depth behavior:

• Current directory: Only media linked directly on the current page is included.
• Custom depth 1: Scans one level below the current page.
• Higher custom depth: Scans deeper nested folder trees.
• Maximum custom depth is clamped to the supported UI range.

M3Unator is tested against these listing families:

• Apache mod_autoindex
• Nginx autoindex
• LiteSpeed and OpenLiteSpeed listings
• Lighttpd mod_dirlisting
• IIS directory browsing
• Caddy file_server browse

It also includes heuristics for similar index pages. It intentionally avoids mounting on ordinary websites that only happen to contain many links.

Video:

mp4 mkv avi webm mov flv wmv m4v mpg mpeg 3gp vob ts mts m2ts divx xvid asf ogv rm rmvb wtv qt hevc f4v swf vro ogx drc gifv mxf roq nsv

Audio:

mp3 m4a wav flac aac ogg wma opus aiff ape mka ac3 dts m4b m4p m4r mid midi mp2 mpa mpc ra tta voc vox amr awb dsf dff alac wv oga sln aif pcm

Normal scan mode:

• Starts with conservative concurrency.
• Adapts up to a higher request limit when the server is responsive.
• Reduces pressure when failures, timeouts, rate limits, or event-loop lag are detected.

Fast scan mode:

• Uses higher starting concurrency.
• Can scan trusted fast servers more quickly.
• Should be avoided on unknown, slow, or fragile servers.

Operational limits:

• Very large directory trees can still take time.
• Browser memory is finite; very large playlists can stress the tab.
• Server rate limiting or blocking can slow or stop recursive scans.
• The script creates playlists; it does not download the media files itself.

M3Unator is designed to run locally.

• No scanned URLs are uploaded to a service.
• No generated playlist is uploaded to a service.
• Directory pages are fetched directly by the browser.
• Playlist names are sanitized before being used as file names.
• Playlist metadata is escaped where needed.
• Permanent HTTP errors such as 401, 403, 404, and 410 are not retried unnecessarily.

As with any userscript, install only from sources you trust and review permissions before enabling it.

Possible causes:

• The page is not a recognized directory listing.
• The page is rendered by a JavaScript file manager instead of server-side index HTML.
• The directory is private or blocked.
• The userscript manager is disabled.
• Browser extension developer mode is required but not enabled.

Possible causes:

• The page links do not point directly to supported media extensions.
• Video or Audio toggles are disabled.
• Files are behind redirects or generated links that do not expose normal file names.
• The server listing format is too custom for the current parser.

Possible causes:

• The depth is too low.
• A linked page does not look like a directory listing.
• The server blocks repeated requests.
• The linked folder URL is malformed or inaccessible.

M3Unator keeps nested path labels so users can distinguish files with similar names. If IPTV categories are desired, use First folder group-title mode to move the first path segment into group-title while preserving the remaining path in the visible title.

Use .m3u8. The UTF-8 BOM improves compatibility with some older IPTV players and devices.

The runtime is currently implemented as a userscript with a main PlaylistGenerator class and a small LogCache helper.

Key runtime responsibilities:

• Detect whether the current page is a directory listing.
• Build and manage the popup UI.
• Parse directory HTML.
• Fetch subdirectories with retry and timeout handling.
• Maintain scan state, pause/resume/cancel state, counters, and logs.
• Build sorted playlist output.
• Apply optional group-title behavior.
• Trigger browser-side file download.

Important output helpers:

• Decode URL and HTML encoded title segments.
• Sort entries by depth and natural title order.
• Escape M3U attribute values.
• Add UTF-8 BOM for .m3u8.
• Keep standard output unchanged when Group Title is empty.

Before publishing a new version:

1. Update @version in userscript metadata.
2. Confirm @license remains OpenUserJS-compatible: GPL-3.0-or-later.
3. Run the local build.
4. Run logic tests.
5. Run lint.
6. Run browser smoke tests for Chromium, Firefox, and WebKit when UI or scanning behavior changes.
7. Check README, changelog, wiki, OpenUserJS text, and promotion notes for outdated feature descriptions.
8. Confirm commit metadata only shows the intended author.
9. Push to GitHub.
10. Update Greasy Fork and OpenUserJS if publishing there.

• GitHub: https://github.com/hasanbeder/M3Unator
• Greasy Fork: https://greasyfork.org/en/scripts/521593-m3unator-web-directory-playlist-creator
• OpenUserJS: https://openuserjs.org/scripts/hasanbeder/M3Unator_-_Web_Directory_Playlist_Creator
• Issues: https://github.com/hasanbeder/M3Unator/issues