mx-dlp

mx-dlp is a terminal-first MX Player downloader, streamer, and catalog indexer with a polished CLI, search flow, and packaging built for real-world installation.

Install

Runtime requirements

• Python 3.10+
• mpv for the best --stream experience
• vlc plus ffmpeg if you want VLC-based streaming

Recommended: global install with pipx

pipx install mx-dlp
mx-dlp --help

To install directly from source:

pipx install .
mx-dlp --search "cricket"

Standard Python install

python3 -m pip install mx-dlp
mx-dlp --help

npm global install

npm install -g mx-dlp
mx-dlp --help

Note:

• the npm package runs the Python CLI from this project
• Python 3 must be installed on the machine for the npm package to work
• if you want no Python dependency, use the standalone binary release instead

Use in a Node.js project

Install inside your Node.js app:

npm install mx-dlp

Then call the CLI from your Node code with child_process.

Simple example:

import { execSync } from "node:child_process";

execSync('npx mx-dlp --search "cricket" --number 5', {
  stdio: "inherit",
});

Recommended example with spawn:

import { spawn } from "node:child_process";

const child = spawn("npx", ["mx-dlp", "--search", "cricket", "--number", "5"], {
  stdio: "inherit",
  shell: process.platform === "win32",
});

child.on("close", (code) => {
  console.log(`mx-dlp finished with code ${code}`);
});

Download a stream URL from Node.js:

import { spawn } from "node:child_process";

const mxdlp = spawn(
  "npx",
  [
    "mx-dlp",
    "--url",
    "https://www.mxplayer.in/movie/watch-varisu-hindi-movie-online-04c78559cceaaa49ec1ce2764a5cd331",
    "--quality",
    "720p",
  ],
  {
    stdio: "inherit",
    shell: process.platform === "win32",
  },
);

mxdlp.on("close", (code) => {
  console.log(`download finished with code ${code}`);
});

Stream directly in mpv from Node.js:

import { spawn } from "node:child_process";

const mxdlp = spawn(
  "npx",
  ["mx-dlp", "--search", "aashram", "--first", "--stream", "--player", "mpv"],
  {
    stdio: "inherit",
    shell: process.platform === "win32",
  },
);

mxdlp.on("close", (code) => {
  console.log(`stream finished with code ${code}`);
});

Important notes for Node.js users:

• mx-dlp is a CLI tool, not a native JavaScript SDK
• in Node.js projects, the normal pattern is to run it with npx mx-dlp ... or the installed binary
• the npm package currently requires Python 3 on the machine
• output files are written to the current working directory unless you run the command from another folder

Run as a module

python3 -m mxdlp --search "cricket"

Features

• Global CLI entrypoint: mx-dlp
• Download mode plus external-player streaming mode
• Player integration for mpv and vlc
• Backend engine for MX landing pages such as web-series, movies, new-release, and list
• Modern pyproject.toml packaging
• PyPI-ready metadata
• pipx-friendly install flow
• Standalone binary build path with PyInstaller

Usage

mx-dlp --search "cricket"
mx-dlp --search "pushpa" --number 10
mx-dlp --search "aashram" --first --quality 720p
mx-dlp --url "https://www.mxplayer.in/movie/watch-..." --quality 1080p
mx-dlp --backend --number 10
mx-dlp --catalog "https://www.mxplayer.in/web-series,https://www.mxplayer.in/movies"
mx-dlp --url "https://www.mxplayer.in/web-series"
mx-dlp --search "aashram" --first --stream
mx-dlp --url "https://www.mxplayer.in/movie/watch-..." --stream --player mpv --player-arg=--fullscreen

Modes

• --search queries MX search and prints matching titles
• --backend indexes the built-in MX landing pages: web-series, movies, new-release, and list
• --catalog indexes one or more custom MX landing page URLs
• --url accepts either a title URL or a catalog URL and auto-detects the correct flow
• --first immediately hands the first result to download or streaming mode

Backend Engine

Use the backend engine when you want mx-dlp to ingest MX landing pages and surface the playable titles behind them.

Built-in backend sources:

• https://www.mxplayer.in/web-series
• https://www.mxplayer.in/movies
• https://www.mxplayer.in/new-release
• https://www.mxplayer.in/list

Examples:

mx-dlp --backend
mx-dlp --backend --number 20
mx-dlp --backend --first --stream
mx-dlp --catalog "https://www.mxplayer.in/web-series,https://www.mxplayer.in/movies"
mx-dlp --url "https://www.mxplayer.in/web-series"

Notes:

• --backend indexes the built-in MX landing pages above
• --catalog accepts one or more comma-separated MX landing page URLs
• if --url points at a landing page instead of a title page, mx-dlp automatically switches to backend indexing mode
• --first works here too, so you can index a backend source and immediately stream or download the first playable title
• result cards include the backend source page so you can see where each title came from

Streaming

Use --stream when you want a yt-dlp-style "open in player now" flow instead of writing an .mp4 file first.

Examples:

mx-dlp --url "https://www.mxplayer.in/movie/watch-..." --stream
mx-dlp --url "https://www.mxplayer.in/movie/watch-..." --stream --player mpv
mx-dlp --url "https://www.mxplayer.in/movie/watch-..." --stream --player vlc
mx-dlp --search "aashram" --first --stream --player-arg=--fullscreen

Notes:

• --player auto prefers mpv
• vlc streaming uses an ffmpeg bridge so MX headers are preserved across DASH playback
• repeat --player-arg to pass extra options straight to your player
• use --player-path /path/to/player if the executable is not on your PATH
• if the requested quality is unavailable, mx-dlp falls back to the best available stream and prints the fallback it chose

Use In Any Project

You can use mx-dlp in other projects in two simple ways:

• call the global CLI from your app, script, or backend job
• import the Python modules directly inside your code

1. Use the global CLI from any project

Install once:

pipx install mx-dlp

Or with npm:

npm install -g mx-dlp

Then call it from any folder on your machine:

mx-dlp --search "cricket"
mx-dlp --url "https://www.mxplayer.in/movie/watch-..." --quality 720p
mx-dlp --backend --number 10

Example in a shell script:

#!/usr/bin/env bash
set -e

mx-dlp --search "aashram" --first --quality 720p

Example in Node.js:

import { execSync } from "node:child_process";

execSync('mx-dlp --search "cricket" --number 5', {
  stdio: "inherit",
});

Example in Python with subprocess:

import subprocess

subprocess.run(
    ["mx-dlp", "--search", "cricket", "--number", "5"],
    check=True,
)

Example indexing backend sources from a Python app:

import subprocess

subprocess.run(
    ["mx-dlp", "--backend", "--number", "10"],
    check=True,
)

2. Use mx-dlp as a Python package in your project

Install it in your app environment:

python3 -m pip install mx-dlp

Search titles programmatically:

from mxdlp.services.search import MXSearch

results = MXSearch("cricket").fetch()

for item in results[:5]:
    print(item["title"], item["url"])

Index backend landing pages programmatically:

from mxdlp.services.catalog import MXCatalogEngine

results = MXCatalogEngine.backend().fetch()

for item in results[:10]:
    print(item["title"], item["url"], item.get("source"))

Download from a known MX Player URL:

from mxdlp.core.pipeline import Pipeline

Pipeline(
    "https://www.mxplayer.in/movie/watch-varisu-hindi-movie-online-04c78559cceaaa49ec1ce2764a5cd331",
    "720p",
).run()

Search first, then download inside your own project flow:

from mxdlp.core.pipeline import Pipeline
from mxdlp.services.search import MXSearch

results = MXSearch("aashram").fetch()

if results:
    Pipeline(results[0]["url"], "720p").run()

Search first, then stream in mpv inside your own project flow:

from mxdlp.core.pipeline import Pipeline
from mxdlp.services.search import MXSearch

results = MXSearch("aashram").fetch()

if results:
    Pipeline(results[0]["url"], "720p", stream=True, player="mpv").run()

Output behavior

• --search prints MX Player results in the terminal
• --backend and --catalog print title results extracted from MX landing pages
• --first automatically picks the first result and starts the download or streaming flow
• --stream launches an external player instead of writing a local media file
• title URLs passed to --url go straight into resolution, while catalog URLs passed to --url switch to indexing mode automatically
• downloads are currently written as <quality>.mp4 in the current working directory

So if you run:

mx-dlp --url "https://www.mxplayer.in/movie/watch-..." --quality 720p

The file will be created in your current folder as:

720p.mp4

Development

Install editable mode:

python3 -m pip install -e .

Build wheel and source distribution:

python3 -m pip install build
python3 -m build

Or with pip only:

python3 -m pip wheel --no-deps --no-build-isolation . -w dist

Publish To PyPI

1. Bump the version in mxdlp/__init__.py
2. Build distributions

python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*

After publishing:

pipx install mx-dlp

Publish To npm

1. Make sure package.json version matches mxdlp/__init__.py
2. Log in to npm
3. Publish the package

npm login
npm publish --access public

After publishing:

npm install -g mx-dlp

Standalone Binary

Build a single-file executable with no Python required on the target machine:

python3 -m pip install ".[binary]"
./scripts/build-binary.sh

Output:

• Linux/macOS: dist/mx-dlp
• Windows: dist/mx-dlp.exe

Release Automation

The repository includes a GitHub Actions workflow that can:

• build wheels and sdists
• publish to PyPI on tagged releases
• publish the npm package on tagged releases
• attach standalone binaries to a GitHub release

Tag example:

git tag v0.3.0
git push origin v0.3.0