Pluto TV Series Episode Downloader

A Python script that downloads all episodes from a Pluto TV series JSON file with automatic ad removal.

Features

• 🎬 Downloads all episodes from a series JSON file
• 🚫 Automatically removes ads from video streams
• 📝 Proper episode naming format (Show Name S01E02)
• 📊 Progress tracking with detailed output
• 💾 Optional saving of cleaned m3u8 playlists

Requirements

• Python 3.6+
• yt-dlp (install with: pip install yt-dlp)
• curl (usually pre-installed on macOS/Linux)

Usage

Basic Usage

./scripts/series-downloader.py path/to/series.json

This will download all episodes to the ./downloads directory.

Custom Output Directory

./scripts/series-downloader.py path/to/series.json -o /path/to/output

Keep Cleaned M3U8 Files

./scripts/series-downloader.py path/to/series.json --keep-m3u8

This saves the cleaned m3u8 playlists in a m3u8_files subdirectory.

Custom yt-dlp Path

./scripts/series-downloader.py path/to/series.json --yt-dlp /usr/local/bin/yt-dlp

Examples

Download a series from the sources directory

./scripts/series-downloader.py sources/ned.json

Download with custom output and keep m3u8 files

./scripts/series-downloader.py sources/zoey.json -o ~/Videos/PlutoTV --keep-m3u8

How It Works

1. Load JSON: Reads the series JSON file containing episode metadata
2. Generate URLs: Creates episode URLs using the format:

   https://pluto.tv/on-demand/series/{slug}/season/{season_number}/episode/{episode_slug}
   

3. Fetch M3U8: Uses yt-dlp -g to extract the m3u8 playlist URL
4. Remove Ads: Processes the m3u8 file to remove advertisement segments between #EXT-X-DISCONTINUITY markers
5. Download: Uses yt-dlp --enable-file-urls to download the cleaned episode

Episode Naming

Episodes are saved with the following format:

{Series Name} S{Season}E{Episode}.{ext}

Examples:

• Manual de Supervivencia Escolar de Ned S01E06.mp4
• Manual de Supervivencia Escolar de Ned S02E13.mp4

Season and episode numbers are zero-padded (e.g., S01, S02, E06, E13).

JSON File Format

The script expects JSON files with the following structure:

{
  "slug": "series-slug",
  "name": "Series Name",
  "seasons": [
    {
      "number": 1,
      "episodes": [
        {
          "slug": "episode-slug",
          "name": "Episode Name",
          "number": 1,
          "season": 1
        }
      ]
    }
  ]
}

See the files in the sources/ directory for complete examples.

Command Line Options

Option	Description	Default
json_file	Path to the series JSON file (required)	-
-o, --output	Output directory for downloaded episodes	./downloads
--yt-dlp	Path to yt-dlp executable	yt-dlp
--keep-m3u8	Keep cleaned m3u8 files	False

Output

The script provides detailed progress information:

Series: Manual de Supervivencia Escolar de Ned
Slug: manual-de-supervivencia-escolar-de-ned
Total seasons: 3

Season 1: 8 episode(s)

[1/28] S01E06: Días de enfermo / Certámenes de deletreo
  URL: https://pluto.tv/on-demand/series/manual-de-supervivencia-escolar-de-ned/season/1/episode/dias-de-enfermo-certamenes-de-deletreo-2004-1-6
  → Fetching m3u8 URL...
  → Downloading m3u8 playlist...
  → Removing ads...
  ✓ Removed 3 ad segment(s)
  → Downloading episode...
  ✓ Downloaded successfully!

Troubleshooting

yt-dlp not found

Install yt-dlp: pip install yt-dlp or brew install yt-dlp

Permission denied

Make the script executable: chmod +x scripts/series-downloader.py

Episode download fails

• Check your internet connection
• Verify the episode URL is accessible
• Try running with verbose yt-dlp output: yt-dlp -v <url>

M3U8 URL fetch fails

The episode might not be available on Pluto TV anymore, or the URL format might have changed.

Related Scripts

• ad-remover.py - Standalone ad removal for m3u8 files
• episode-downloader.py - Download from existing m3u8 files
• playlist-downloader.py - Download playlist URLs
• slug-extractor.py - Extract series information

License

This script is provided as-is for educational purposes.