HANDLERS.md

Platform Handlers Documentation

This document describes the platform-specific handlers in the Ultimate Media Downloader. Each handler is designed to work with a specific streaming or content platform, extracting metadata and facilitating downloads.

Overview

Handlers are specialized modules that know how to work with specific platforms. While yt-dlp can download from many sites directly, some platforms require special handling for:

Metadata extraction and embedding
Authentication or cookie management
Content discovery (playlists, albums, channels)
Quality selection
Anti-bot bypass techniques

Handler Location

All handlers are located in the handlers/ directory:

handlers/
    __init__.py
    spotify_handler.py
    apple_music_handler.py
    jiosaavn_handler.py
    gaana_handler.py
    tumblr_handler.py
    linkedin_handler.py
    pinterest_handler.py
    reddit_handler.py
    instagram_handler.py
    pornhub_handler.py
    xnxx_handler.py
    xhamster_handler.py
    hianime_handler.py
    tiktok_handler.py
    eporner_handler.py
    hqporner_handler.py
    beeg_handler.py
    four_k_wallpapers_handler.py

Handler Architecture

Every handler follows a consistent pattern that makes them predictable and easy to understand.

Common Structure

Loading diagram...

Common Methods

Every handler implements these core methods:

Method	Purpose
`__init__(downloader)`	Initialize with reference to main downloader
`search_and_download(url)`	Main entry point for processing URLs
`_print(message)`	Print messages using Rich formatting if available

Spotify Handler

File: handlers/spotify_handler.py

The Spotify Handler enables downloading music from Spotify by searching for equivalent content on YouTube.

How It Works

Loading diagram...

Supported Content Types

Content Type	URL Pattern	Example
Track	`/track/`	`https://open.spotify.com/track/xxx`
Album	`/album/`	`https://open.spotify.com/album/xxx`
Playlist	`/playlist/`	`https://open.spotify.com/playlist/xxx`
Artist	`/artist/`	`https://open.spotify.com/artist/xxx`

Configuration

The handler can use the official Spotify API for better metadata extraction:

# Set environment variables for API access
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"

Without API credentials, the handler scrapes the Spotify webpage for basic information.

Content Type	URL Pattern
Song	`music.apple.com/.../song/...`
Album	`music.apple.com/.../album/...`
Playlist	`music.apple.com/.../playlist/...`
Artist	`music.apple.com/.../artist/...`

Content Type	URL Pattern
Song	`gaana.com/song/...`
Album	`gaana.com/album/...`
Playlist	`gaana.com/playlist/...`
Artist	`gaana.com/artist/...`

Data Source	Purpose
Meta tags (og:title, og:image)	Basic metadata
JSON-LD structured data	Detailed track/album information
Page links	Song discovery for albums/playlists

Factor	Weight
Title match	100 points
Artist match	50 points
Official content	30 points
Audio/lyric video	20 points
View count	Up to 30 points
Like ratio	Up to 15 points
Unwanted keywords	-50 points

Content Type	URL Pattern
Song	`jiosaavn.com/song/...`
Album	`jiosaavn.com/album/...`
Playlist	`jiosaavn.com/featured/...` or `jiosaavn.com/s/playlist/...`
Artist	`jiosaavn.com/artist/...`

Endpoint	Purpose
`autocomplete.get`	Search functionality
`song.getDetails`	Track metadata and streaming URLs
`content.getAlbumDetails`	Album information and track list
`playlist.getDetails`	Playlist contents
`lyrics.getLyrics`	Song lyrics in multiple languages

Method	Purpose
`get_blog_posts()`	Fetch posts from a blog
`get_post_media()`	Extract media URLs from a post
`_call()`	Make authenticated API requests

Content Type	URL Pattern	Example
Single Post	`/p/POST_ID`	`https://instagram.com/p/ABC123`
Single Reel	`/reel/REEL_ID` or `/reels/REEL_ID`	`https://instagram.com/reel/XYZ789`
IGTV Video	`/tv/VIDEO_ID`	`https://instagram.com/tv/DEF456`
Stories	`/stories/USERNAME`	`https://instagram.com/stories/username`
Profile Posts	`/USERNAME/`	`https://instagram.com/username`
Profile Reels	`/USERNAME/reels/`	`https://instagram.com/username/reels`

Option	Description
1	Download all posts (photos and videos)
2	Download all reels
3	Download active stories
4	Download specific range (e.g., posts 1-20)
5	Download as ZIP file (bundled)

Feature	Technology
Browser Automation	Playwright (Chromium)
HTML Parsing	BeautifulSoup4
HTTP Requests	Requests + HTTPAdapter with retry
Progress Display	Rich Console and Progress Bars
Cookie Management	JSON file storage
User Agent	Random rotation from list

Method	Purpose
`can_handle(url)`	Check if URL is Instagram
`download(url, output_dir)`	Main download entry point
`_download_single_post(url)`	Download specific post/reel
`_download_profile_posts(username)`	Download from profile
`_download_stories(url)`	Download stories
`_handle_profile_download(username)`	Interactive menu for profiles
`_init_browser()`	Initialize Playwright browser
`_save_cookies()`	Persist cookies for reuse

Content	URL Pattern
Single Video	`/view_video.php?viewkey=xxx`
Channel	`pornhub.com/channels/xxx`
Model	`pornhub.com/model/xxx`
Playlist	`pornhub.com/playlist/xxx`

Content	Description
Videos	Standard video pages
Channels	Channel video listings
Photo Galleries	Image collections
Categories	Category browsing

Content	Description
Anime Series	Full series with all episodes
Episodes	Individual episode downloads
Movies	Anime movie files
Manga	Manga chapter collections

Endpoint	Purpose
`store.externulls.com`	Video metadata API
`video.beeg.com`	Video CDN

URL Pattern	Behaviour
`https://4kwallpapers.com/` (root)	Opens `interactive_browse()`
`https://4kwallpapers.com/<category>/`	Category listing (paginated)
`https://4kwallpapers.com/search/?q=query`	Search results (single page, 24 max)
`https://4kwallpapers.com/cat/slug-ID.html`	Single wallpaper download

Method	Description
`interactive_browse(search_query='')`	Main menu shown when user runs `--wallpaper` or types `wallpaper` in interactive mode
`handle_url(url)`	Auto-detects the URL type and routes to the appropriate flow
`fetch_listing(url)`	Fetches wallpapers from a single page
`fetch_listing_paginated(base_url, max_wallpapers=200)`	Paginates via `?page=N`, deduplicates by ID, stops on <20 results or duplicates
`search_wallpapers(query)`	Queries `https://4kwallpapers.com/search/?q=<query>` — single page only
`fetch_popular_tags()`	Scrapes live tag links from the homepage navigation
`_parse_wallpaper_listing(html)`	Parses `<a href="...cat/slug-ID.html">` links from listing HTML
`_parse_download_links(html)`	Extracts `/images/wallpapers/` hrefs with resolution regex `(\d{3,5}x\d{3,5})`
`_parse_selection(raw, total)`	Converts `"1,3,4-7,10-12"` / `"all"` to sorted 0-based index list
`_ask_selection(total)`	Interactive prompt that calls `_parse_selection`
`_run_listing_flow(section_name, listing_url)`	Full browse → select → download flow for any listing URL

Content Type	URL Pattern	Example
Single Track	`/watch?v=...`	`https://music.youtube.com/watch?v=xxx`
Playlist	`/playlist?list=...`	`https://music.youtube.com/playlist?list=xxx`
Album/Browse	`/browse/...`	`https://music.youtube.com/browse/xxx`

Content Type	URL Pattern	Example
Track	`/albums/...`	`https://music.amazon.com/albums/xxx?trackAsin=yyy`
Album	`/albums/...`	`https://music.amazon.com/albums/xxx`
Playlist	`/playlists/...`	`https://music.amazon.com/playlists/xxx`
Artist	`/artists/...`	`https://music.amazon.com/artists/xxx`

Content Type	URL Pattern	Example
Track	`/songs/...`	`https://www.boomplay.com/songs/xxx`
Album	`/albums/...`	`https://www.boomplay.com/albums/xxx`
Playlist	`/playlists/...`	`https://www.boomplay.com/playlists/xxx`
Artist	`/artists/...`	`https://www.boomplay.com/artists/xxx`

Content Type	URL Pattern	Example
Song	`/song/...`	`https://audiomack.com/user/song/xxx`
Album	`/album/...`	`https://audiomack.com/user/album/xxx`
Playlist	`/playlist/...`	`https://audiomack.com/user/playlist/xxx`
Artist	`/artist/...`	`https://audiomack.com/user`

Content Type	URL Pattern	Example
Single Video	`/video/...`	`https://www.dailymotion.com/video/xxx`
Collection	`/(user	playlist)/...`

Content Type	URL Pattern	Example
Single Video	`vimeo.com/...`	`https://vimeo.com/xxx`
Collection	`/channels/...`	`https://vimeo.com/channels/xxx`

Content Type	URL Pattern	Example
Single Video	`rumble.com/...`	`https://rumble.com/xxx.html`
Channel	`/c/...`	`https://rumble.com/c/xxx`

Content Type	URL Pattern	Example
VOD	`/videos/...`	`https://www.twitch.tv/videos/xxx`
Clip	`clips.twitch.tv/...`	`https://clips.twitch.tv/xxx`
Live Stream	`twitch.tv/...`	`https://www.twitch.tv/xxx`

Content Type	URL Pattern	Example
VOD	`/video/...`	`https://kick.com/video/xxx`
Live Stream	`kick.com/...`	`https://kick.com/xxx`

Content Type	URL Pattern	Example
Talk	`/talks/...`	`https://www.ted.com/talks/xxx`
Collection	`/playlists/...`	`https://www.ted.com/playlists/xxx`

Content Type	URL Pattern	Example
Single Video	`/video/...`	`https://www.bitchute.com/video/xxx`
Channel	`/channel/...`	`https://www.bitchute.com/channel/xxx`

Content Type	URL Pattern	Example
Single Photo	`/photos/.../...`	`https://www.flickr.com/photos/user/xxx`
Album	`/albums/...`	`https://www.flickr.com/photos/user/albums/xxx`
User Stream	`/photos/...`	`https://www.flickr.com/photos/user/`

Content Type	URL Pattern	Example
Single Video	`/w/...`	`https://peertube.example.com/w/xxx`
Channel	`/c/...`	`https://peertube.example.com/c/xxx`
Playlist	`/w/p/...`	`https://peertube.example.com/w/p/xxx`

Content Type	URL Pattern	Example
Single Video	`/watch/...`	`https://www.veoh.com/watch/xxx`
User Channel	`/users/...`	`https://www.veoh.com/users/xxx`

Content Type	URL Pattern	Example
Single Video	`/watch/...`	`https://www.trillertv.com/watch/xxx`
Show/Event	`/vl/...`	`https://www.trillertv.com/vl/xxx`