M3U8 Downloader

A Python script to download M3U8 playlists, download all segments, and combine them into a single MP3 file.

Features

• ✅ Download M3U8/HLS playlists
• ✅ Handle both master playlists and media playlists
• ✅ Download video/audio segments automatically
• ✅ Combine segments into a single file
• ✅ Convert to MP3 format
• ✅ Progress tracking during download
• ✅ Automatic cleanup of temporary files
• ✅ Robust error handling

Requirements

• Python 3.6+
• ffmpeg (for combining and converting audio)
• requests library

Installation

1. Clone or download this repository
2. Run the setup script:

   ./setup.sh

This will:

• Create a Python virtual environment in the venv directory
• Install all required dependencies
• Check for ffmpeg availability

Usage

Option 1: Using the convenience script (recommended)

# Basic usage - saves to ./downloads/ by default
./run.sh "https://audio.mixcloud.stream/secure/hls/4/7/d/7/bad2-ba36-4b6b-889d-d873c74b5a21.m4a/streamindex-a1.m3u8"

# With custom output filename in default directory
./run.sh "https://example.com/playlist.m3u8" -o "my_audio.mp3"

# With custom output directory
./run.sh "https://example.com/playlist.m3u8" -d "/path/to/my/outputs"

# With both custom directory and filename
./run.sh "https://example.com/playlist.m3u8" -d "/path/to/my/outputs" -o "my_audio.mp3"

# Show help
./run.sh --help

Option 2: Manual activation

# Activate virtual environment
source venv/bin/activate

# Basic usage - saves to ./downloads/ by default
python3 m3u8_downloader.py "https://example.com/playlist.m3u8"

# With custom output filename
python3 m3u8_downloader.py "https://example.com/playlist.m3u8" -o "my_audio.mp3"

# With custom output directory
python3 m3u8_downloader.py "https://example.com/playlist.m3u8" -d "/path/to/outputs"

Dependencies

Make sure ffmpeg is installed on your system:

# Install ffmpeg (macOS)
brew install ffmpeg

# Install ffmpeg (Ubuntu/Debian)
sudo apt install ffmpeg

How It Works

1. Download Playlist: Fetches the M3U8 playlist file
2. Parse Playlist: Extracts individual segment URLs
3. Handle Master Playlists: If the URL points to a master playlist, it finds and downloads the media playlist
4. Download Segments: Downloads all video/audio segments in parallel
5. Combine Segments: Uses ffmpeg to concatenate all segments
6. Convert to MP3: Converts the final output to MP3 format if needed
7. Cleanup: Removes temporary files

Supported Formats

• Input: M3U8/HLS playlists (HTTP/HTTPS)
• Segment Formats: .ts, .m4a, .mp4, .webm
• Output: MP3 (128kbps)

Error Handling

The script includes robust error handling for:

• Network connectivity issues
• Invalid M3U8 URLs
• Missing segments
• ffmpeg errors
• File system errors

Examples

Mixcloud Download

python3 m3u8_downloader.py "https://audio.mixcloud.stream/secure/hls/path/to/streamindex-a1.m3u8"

YouTube Live Stream

python3 m3u8_downloader.py "https://manifest.googlevideo.com/api/manifest/hls_playlist/..."

Twitch VOD

python3 m3u8_downloader.py "https://vod-secure.twitch.tv/path/to/playlist.m3u8"

Troubleshooting

ffmpeg Not Found

Make sure ffmpeg is installed and available in your PATH:

ffmpeg -version

Permission Denied

Make sure you have write permissions to the output directory.

Network Errors

Some streams may require specific headers or authentication. The script includes user-agent headers, but some services may require additional authentication.

Segment Download Failures

The script will continue downloading other segments if some fail. Check your network connection if many segments fail.

License

This project is provided as-is for educational purposes. Please respect the terms of service of the streaming platforms you're downloading from.

Contributing

Feel free to submit issues and enhancement requests!