media-stream-util

Media Stream Utility

A CLI utility for downloading media content from playlist.json URLs or webpages containing embedded media players.

Platform Support

Currently supports: Vimeo content only

Note: Support for additional video platforms (YouTube, Dailymotion, etc.) will be added in future releases.

⚠️ LEGAL DISCLAIMER

This tool is provided for PERSONAL, EDUCATIONAL, and ARCHIVAL purposes only.

YOUR RESPONSIBILITIES:

• ✅ Comply with all applicable copyright laws
• ✅ Respect content creators' intellectual property rights
• ✅ Follow the platform's Terms of Service
• ✅ Ensure you have proper authorization to download content
• ✅ Use only for personal, educational, or archival purposes

IMPORTANT LIMITATIONS:

• 🚫 This software does NOT bypass DRM or access encrypted content
• 🚫 Does NOT work with protected or premium content
• 🚫 Only works with publicly accessible, unencrypted streams
• ⚠️ Users must provide their own cookies for authenticated content

Use at your own risk and responsibility.

Installation & Usage

Via NPX (Recommended)

npx media-stream-util [options]

Options

Flag	Description	Example
-p, --jsonPlaylist	Direct link to playlist.json file	-p "https://example.com/playlist.json"
-w, --webPage	Link to webpage with embedded media	-w "https://example.com/page"
-cp, --cookiePath	Path to cookies.json file	-cp "./cookies.json"
-a, --audioOnly	Download audio only	-a
-v, --videoOnly	Download video only (requires resolution)	-v -r 720
-c, --combine	Download and merge audio + video	-c
-r, --resolution	Set video resolution	-r 1080 (options: 240, 360, 540, 720, 1080)
-m, --maxResolution	Download maximum available resolution	-m
-o, --output	Output filename	-o "my-video"
--path	Output directory path	--path "./downloads"
--help	Show help	--help
--version	Show version	--version
--disclaimer	Prints disclaimer	--disclaimer

Examples

# Download audio only from direct playlist URL
npx media-stream-util -p "https://example.com/playlist.json" -a -o "audio-file"

# Download 720p video from webpage with cookies
npx media-stream-util -w "https://example.com/page" -cp "./cookies.json" -v -r 720 -o "video-file"

# Download and combine audio+video at max resolution
npx media-stream-util -p "https://example.com/playlist.json" -c -m -o "combined-file"

Cookie Format

If accessing authenticated content, provide cookies in JSON format:

[
  {
    "name": "session_id",
    "value": "your_session_value",
    "domain": ".example.com",
    "path": "/",
    "secure": true,
    "httpOnly": true
  }
]

Requirements

• Node.js 14+
• FFmpeg (will prompt to install if missing)

Technical Notes

• Only works with unencrypted HLS/DASH streams
• Requires direct access to playlist.json or embedded player URLs
• Does not perform web scraping or automated platform interaction
• All URLs and authentication must be provided by the user

License

MIT License - See LICENSE file for details.

This software is provided "as is" without warranty of any kind.

Support

This tool is provided as-is for educational purposes. Users are responsible for ensuring their usage complies with applicable laws and platform terms of service.