1. خانه
  2. راهنما
  3. خط فرمان و اتوماسیون

خط فرمان و اتوماسیون

MDM را می‌توان بدون پنجره‌اش به سه روش کنترل کرد:

  • خط فرمان خود برنامه، همان سوئیچ‌های IDM: یک بارگیری را از یک اسکریپت، یک فایل دسته‌ای یا برنامه دیگر به برنامه در حال اجرا بسپارید.
  • mattdownloadmanager-cli، یک ابزار خط فرمان جداگانه: فایل‌ها، ویدیوها و تورنت‌ها را در یک ترمینال، با نمایش پیشرفت، بدون نیاز به برنامه بارگیری کنید.
  • رابط برنامه‌نویسی کاربردی (API) خودکارسازی: برنامه‌های دیگر، بارگیری‌های برنامه در حال اجرا را (به صورت JSON) فهرست می‌کنند و آن‌ها را از طریق یک کانال محلی و محافظت‌شده با توکن، متوقف، شروع، حذف یا پاک می‌کنند. دستیاران هوش مصنوعی از طریق سرور MCP برنامه MDM از آن استفاده می‌کنند: به دستیاران هوش مصنوعی مراجعه کنید.

برای اجرای کل برنامه بدون پنجره، روی سرور خانگی یا NAS، به اجرای MDM روی سرور (mattdownloadmanager --headless) مراجعه کنید؛ برای کنترل آن از طریق تلفن، کنترل MDM از طریق تلفن شما را ببینید.

مثال‌ها از مسیرهای Windows استفاده می‌کنند؛ در macOS و Linux برنامه‌ها همین نام‌ها را بدون .exe دارند.

خط فرمان برنامه

mattdownloadmanager.exe /d URL [/p folder] [/f name] [/a] [/n] [/s]
سوئیچ آنچه انجام می‌دهد
/d URL آدرس برای بارگیری.
/p folder آن را در این پوشه ذخیره کنید (در غیر این صورت پوشه دسته از گزینه‌ها ← ذخیره در).
/f name آن را با این نام ذخیره کنید.
/a آن را به صف اصلی بارگیری اضافه کنید بدون اینکه شروع شود.
/n بی‌صدا: بدون پنجره اطلاعات فایل بارگیری، بارگیری بلافاصله شروع می‌شود (یا با /a در صف قرار می‌گیرد).
/s صف اصلی بارگیری را شروع کنید.
/exit برنامه در حال اجرا را ذخیره و ببندید (نصب‌کننده قبل از ارتقا از آن استفاده می‌کند).
/startup Start in the notification area, the window hidden: what Launch Matt Download Manager on startup starts MDM with when you sign in. Where no notification area shows MDM's icon (some Linux desktops), MDM starts minimized. A running MDM stays as it is.
یک فایل .torrent یا لینک magnet: آن را در افزودن تورنت باز کنید (چیزی که Windows وقتی MDM تورنت‌ها را باز می‌کند، ارسال می‌کند).

سوئیچ‌ها می‌توانند با / یا - شروع شوند، در هر صورت. اگر MDM در حال اجرا باشد، دستور به آن می‌رود؛ در غیر این صورت، MDM شروع شده و آن را اجرا می‌کند. برای مثال:

mattdownloadmanager.exe /d https://example.com/files/report.pdf /p D:\Reports /n
mattdownloadmanager.exe /d https://example.com/big.iso /a
mattdownloadmanager.exe /s

mattdownloadmanager-cli

این ابزار همراه با هر بارگیری MDM، در کنار برنامه (نصب‌کننده آن را در پوشه MDM قرار می‌دهد) ارائه می‌شود. این ابزار به تنهایی کار می‌کند: برنامه نیازی به اجرا ندارد، به جز برای status و api.

دستور آنچه انجام می‌دهد
get URL [-o folder\|file] [-c connections] [-H "Header: value"]... [--checksum hash] [--dns choice] [--adapter name] فایلی را با حداکثر 8 اتصال (-c، 1 تا 128)، با نمایش پیشرفت، بارگیری می‌کند. Ctrl+C آن را متوقف می‌کند؛ resume ادامه می‌دهد. --checksum فایل تمام‌شده را بررسی می‌کند: MD5، SHA-1، SHA-256، SHA-512 یا CRC32 هگزادسیمال، که به صورت اختیاری نام‌گذاری شده است (sha256:…). --dns DNS را انتخاب می‌کند: system (پیش‌فرض)؛ یک سرویس و نحوه درخواست آن، cloudflare-https، quad9-tls، google-plain، adguard-https، nextdns-tls؛ آدرس‌های سرورهای DNS، 9.9.9.9,149.112.112.112؛ یا یک آدرس DNS-over-HTTPS. هرگز به DNS سیستم بازنمی‌گردد. --adapter هر اتصال را از طریق یک آداپتور شبکه، با نام آن (Ethernet، wg0) یا یکی از آدرس‌های آن ارسال می‌کند؛ وقتی متصل نباشد، چیزی ارسال نمی‌شود و بارگیری با شکست مواجه می‌شود. پیوندی از یک میزبان فایل که یکی از حساب‌های debrid شما (Options → Accounts) پشتیبانی می‌کند، مانند برنامه، از طریق آن حساب می‌رود و get می‌گوید through Real-Debrid؛ --direct خود آدرس را بارگیری می‌کند (Debrid service accounts).
resume file.mdm.json [-c connections] [-H ...] [--direct] یک بارگیری متوقف شده یا خراب را از فایل .mdm.json کنار آن ادامه می‌دهد. از طریق یک حساب debrid، مانند get: سرویس یک پیوند جدید می‌دهد وقتی پیوند قدیمی منقضی شده باشد؛ --direct از خود آدرس ادامه می‌دهد.
install-gallery-dl gallery-dl را برای گالری‌های تصویر نصب یا به‌روزرسانی کنید: فهرست جمع‌کنترلی آن با کلید امضای نویسنده‌اش، و برنامه با آن فهرست بررسی می‌شود (Windows و Linux x86-64؛ در جاهای دیگر خودتان آن را نصب کنید).
gallery-get URL [-o folder] [--limit N] [--adapter name] تصاویر یک گالری (مانند دسته‌بندی در Wikimedia Commons یا آلبوم در Flickr) را در پوشه‌ای به نام آن، داخل -o بارگیری می‌کند. --limit حداکثر به همان تعداد، یعنی اولین موارد فهرست‌شده توسط سایت را دریافت می‌کند. اگر دوباره اجرا شود، فقط موارد جدید را واکشی می‌کند. بارگیر داخلی MDM، تصاویر فهرست‌شده توسط gallery-dl را چهارتا چهارتا دریافت می‌کند. --adapter اتصالات MDM و gallery-dl را از طریق یک آداپتور شبکه، مانند get، ارسال می‌کند.
video-info URL چه ویدیویی در یک صفحه وجود دارد (YouTube، Vimeo، ...) و کیفیت‌های قابل انتخاب.
playlist-info URL [--from N] [--count N] ویدئوهای یک فهرست پخش یا کانال، هر کدام در یک سطر به ترتیبی که فهرست شده‌اند: مکان، مدت، عنوان و نشانی آن.
playlist-get URL [-f selector] [-o folder] [-c pieces] [--from N] [--count N] ویدیوهای یک فهرست پخش یا کانال را یکی پس از دیگری، در پوشه‌ای به نام فهرست در -o بارگیری می‌کند. -f یک کیفیت برای همه است، مانند video-get (به‌طور پیش‌فرض بهترین کیفیت هر ویدیو؛ bv*[height<=720]+ba/b[height<=720] = تا 720p؛ ba = صدای اصلی؛ mp3:320، opus:، flac: مانند video-get). -c مانند video-get.
video-get URL [-f selector] [-o folder] [-c pieces] [--subs langs] [--auto-subs] [--embed-subs] [--adapter name] یک ویدیو را بارگیری می‌کند؛ -f یک انتخاب‌گر کیفیت را از video-info می‌گیرد (b = بهترین فایل تکی؛ ba = فقط صدا همان‌طور که سایت دارد، بدون تبدیل؛ mp3:320، mp3:256، mp3:192 یا mp3:128 = صدا به صورت MP3 با آن بیت‌ریت، mp3:0 با بهترین بیت‌ریت متغیر؛ opus: = به صورت Opus؛ flac: = به صورت FLAC، بدون افت کیفیت اما بهتر از صدای سایت نیست؛ تبدیل‌ها به ffmpeg نیاز دارند). -c: بارگیر داخلی MDM هر جریان را که yt-dlp پیدا می‌کند، با این تعداد اتصال (8 به صورت پیش‌فرض، 1 تا 128) می‌آورد، یک جریان تکه‌تکه (HLS, DASH) با این تعداد تکه به صورت هم‌زمان. --subs زیرنویس‌ها را در کنار آن ذخیره می‌کند: کدهای زبان از video-info (en,fr)، یا all برای هر کدام که آپلودکننده داده است؛ --auto-subs به جای آن زیرنویس‌های خودکار سایت را می‌گیرد؛ --embed-subs آن‌ها را در ویدیو قرار می‌دهد (به ffmpeg، MP4 یا MKV نیاز دارد). با ffmpeg، فصل‌های ویدیو نیز به فایل اضافه می‌شوند، همان‌طور که تعبیه فصل‌ها در دانلود ویدیو انجام می‌دهد. --adapter اتصالات بارگیری‌ها، و اتصالات yt-dlp (و ffmpeg) را از طریق یک آداپتور شبکه می‌فرستد، مانند get؛ وقتی متصل نباشد، چیزی شروع نمی‌شود.
install-ytdlp, install-ffmpeg Install or update the helpers videos need: yt-dlp (checked against its signing key) and ffmpeg (x64 and ARM64 Windows; on macOS and Linux MDM uses the system's, and on 32-bit Windows one you choose in Helpers).
torrent-info SOURCE نام، فایل‌ها (شماره‌گذاری‌شده) و اندازه یک تورنت؛ SOURCE پیوند مگنت یا فایل .torrent است.
torrent-get SOURCE [-o folder] [--files 0,2] [--use-existing] یک تورنت یا فقط بعضی از فایل‌های آن را بارگیری کنید. اگر بعضی از فایل‌های آن از قبل در پوشه باشند، عملیات متوقف می‌شود و نام آن فایل‌ها نمایش داده می‌شود؛ --use-existing به‌جای آن‌ها از فایل‌های موجود استفاده می‌کند (فایل‌های منطبق نگه داشته می‌شوند و بقیه بارگیری می‌شوند).
torrent-create PATH -o file.torrent از یک فایل یا پوشه .torrent بسازید (همتاها آن را از طریق DHT پیدا می‌کنند).
status بارگیری‌های برنامه در حال اجرا، به صورت JSON، با شناسه‌های آن‌ها (API خودکارسازی باید روشن باشد).
pause ID..., start ID... بارگیری‌های در حال اجرا را متوقف کنید، یا بارگیری‌های متوقف‌شده، در صف یا ناموفق را در برنامه در حال اجرا شروع کنید (از سر بگیرید).
remove ID..., delete ID... بارگیری‌ها را از فهرست برنامه در حال اجرا بردارید: remove فایل‌هایشان را نگه می‌دارد و delete آن‌ها را هم حذف می‌کند. بارگیری در حال اجرا ابتدا متوقف می‌شود (pause).
api on, api off API خودکارسازی برنامه در حال اجرا را روشن یا خاموش کنید.

mattdownloadmanager-cli help <command>همه گزینه‌ها را نشان می‌دهد. دستوری که با خطا مواجه شود (برنامه در حال اجرا نباشد، با خطا پاسخ دهد یا بارگیری قطع شود)، با کد 1 خارج می‌شود. برای مثال:

mattdownloadmanager-cli get https://example.com/big.iso -o D:\Downloads -c 16 --checksum sha256:9f86d0…
mattdownloadmanager-cli video-get "https://www.youtube.com/watch?v=aqz-KE-bpKQ" -f "b[height=720]"
mattdownloadmanager-cli torrent-get "magnet:?xt=urn:btih:…" --files 0

JSON برای اسکریپت‌ها و برنامه‌ها

با --json (قبل یا بعد از دستور)، هر دستور به جای متن، JSON را چاپ می‌کند، هر شیء در یک خط، تا اسکریپت‌ها و عوامل هوش مصنوعی آن را بخوانند:

دستور چاپ می‌کند
get, resume {"event": "through", "service"}ابتدا وقتی بارگیری از طریق حساب debrid انجام می‌شود، سپس هر نیم‌ثانیه یک خط {"event": "progress", "downloaded", "size", "speed", "connections", "segments"}، بعد {"event": "done", "path", "size", "seconds"} یا پس از Ctrl+C، {"event": "paused", "state"} (state فایلی است که resume دریافت می‌کند).
video-get {"event": "progress", "downloaded", "size", "speed"}خط‌ها، سپس {"event": "done", "path", "subtitles", "subtitle_problems"}: فایل‌های زیرنویسی که کنار آن ذخیره شده‌اند و زبان‌هایی که سایت نپذیرفته است ({"code", "name", "reason", "beside"}؛ beside: این فایل‌ها در تلاش دوم، به‌جای داخل ویدئو، کنار آن قرار گرفتند).
torrent-get {"event": "progress", "phase", "downloaded", "size", "speed", "peers", "peers_seen"}خط‌ها، سپس {"event": "done", "path", "size"} یا {"event": "stopped", "downloaded", "seconds"} همراه با --seconds.
video-info {"title", "choices": [{"label", "format", "size", "approx", "height", "fps", "codec", "range"}], "subtitles": [{"code", "name", "automatic"}], "declared"}; declared is the address of the video the page says it is about, when that one was looked up instead of the first player in its HTML (on a site yt-dlp has no reader of its own for), else null; a choice's format is what video-get -f takes (the very formats it was sized from, as 401+251, then the nearest should those be gone), approx says its size is an estimate, codec is AV1, VP9, H.264…, range is HDR (or SDR beside an HDR choice); a subtitle's code is what --subs takes.
torrent-info {"name", "info_hash", "size", "files": [{"index", "size", "path"}]}.
torrent-create {"info_hash", "path"}.
install-ytdlp, install-ffmpeg {"tool", "version", "path"}.
status، pause، start، remove، delete،api پاسخ برنامه، که از قبل JSON است (به زیر مراجعه کنید).

اندازه‌ها بر حسب بایت هستند (null در صورت نامشخص بودن) و سرعت‌ها بر حسب بایت بر ثانیه. در صورت بروز خطا، {"error": "…"} چاپ می‌شود و برنامه با کد 1 خارج می‌شود. برای مثال:

mattdownloadmanager-cli --json get https://example.com/big.iso -o D:\Downloads
{"event":"progress","downloaded":4194304,"size":1073741824,"speed":52428800,"connections":8,"segments":8}
…
{"event":"done","path":"D:\\Downloads\\big.iso","size":1073741824,"seconds":20.4}

API خودکارسازی

برنامه‌های دیگر می‌توانند از برنامه در حال اجرا بپرسند چه چیزی را بارگیری می‌کند و بارگیری‌ها را متوقف، شروع، از فهرست حذف یا حذف کنند. API به‌طور پیش‌فرض خاموش است؛ آن را با mattdownloadmanager-cli api on روشن کنید (و با api off خاموش کنید).

نحوه ارتباط برنامه‌ها با MDM

  1. هنگام اجرا، MDM به پورتی در 127.0.0.1 (فقط روی همین رایانه) گوش می‌دهد و شماره پورت و یک توکن محرمانه را در ipc.json در پوشه داده‌هایش می‌نویسد: - Windows: %APPDATA%\mattdownloadmanager\ipc.json - macOS: ~/Library/Application Support/mattdownloadmanager/ipc.json - Linux: ~/.local/share/mattdownloadmanager/ipc.json - نسخه قابل‌حمل: data\ipc.json کنار برنامه.

توکن با هر بار اجرا تغییر می‌کند؛ فقط برنامه‌هایی که به پوشه داده‌های خودتان دسترسی دارند می‌توانند از آن استفاده کنند. 2. به آن پورت وصل شوید و یک خط JSON بفرستید که شامل توکن و فیلدهای دستور باشد، مثلا {"token": "<token>", "query": "list"}. 3. MDM با یک خط پاسخ می‌دهد: ok برای یک دستور، یا یک شیء JSON برای یک پرس‌وجو.

دستورهای قابل‌استفاده

فیلدها (به‌جز token) پاسخ
{"query": "list"} هر دانلود و سرعت کلی: {"downloads": [{"id", "file", "url", "path", "status", "size", "downloaded", "speed", "added", "category", "error"}], "speed": bytes per second, "queues": [{"name", "running", "ids"}], "categories": [{"key", "name"}], "free": bytes}. status می‌تواند Queued، Downloading، Stopped، Complete یا Error باشد؛ size در حالی که نامعلوم است، null است؛ error (چرا شکست خورد) فقط برای دانلودی در Error وجود دارد؛ category key یک دسته است؛ free فضای خالی است که دانلودها به آنجا می‌روند (null وقتی نامعلوم است). فقط زمانی که API روشن است.
{"action": "pause", "ids": [3, 4]} روی بارگیری‌ها بر اساس شناسه عمل می‌کند: "pause"، "start"، "remove" (فایل نگه داشته می‌شود) یا "delete" (فایل هم حذف می‌شود). پاسخ {"done": [3], "skipped": [{"id": 4, "why": "not running"}]} است؛ پیش از حذف بارگیری از فهرست یا حذف فایل آن، باید بارگیری در حال اجرا را متوقف کرد. فقط وقتی API روشن است.
{"action": "start_queue", "queue": "Main download queue"} صفی با آن نام را شروع می‌کند (یا با "stop_queue"، متوقف می‌کند) (نامی از queues لیست). پاسخ {"done": [], "skipped": []} یا {"error": …, "code": "unknown-queue"}. فقط زمانی که API روشن است.
{"api": true} / {"api": false} API را روشن یا خاموش می‌کند: {"api": true}.
{"url": "https://…", "dir": "D:\\Files", "name": "a.zip", "silent": true} یک دانلود اضافه می‌کند، همانطور که /d /p /f /n خط فرمان انجام می‌دهد ("later": true برابر با /a است)؛ ok. "category" (یک کلید از categories لیست) آن را به جای پوشه‌ای که نوع آن انتخاب می‌کند، در پوشه آن دسته قرار می‌دهد؛ "queue" (نام یک صف) صفی است که در آن با "later" منتظر می‌ماند. همچنین با API خاموش، مانند خط فرمان.
{"start_queue": true} صف اصلی دانلود را شروع می‌کند؛ ok.

یک سوال یا عمل ناشناخته با {"error": "…"} پاسخ داده می‌شود، همانطور که یک سوال در حالی که API خاموش است (سپس با "code": "api-off"، برای بررسی برنامه‌ها: متن خطا ممکن است تغییر کند). یک توکن اشتباه با denied پاسخ داده می‌شود.

هر درخواست و پاسخ، فیلد به فیلد، در یک JSON Schema توضیح داده شده است: automation-api.schema.json (همچنین در https://idm.teachermatt.com/automation-api.schema.json). این از کدی ساخته شده است که برنامه با آن پاسخ می‌دهد، بنابراین دقیق می‌ماند؛ برنامه‌ها می‌توانند آنچه را که ارسال می‌کنند و می‌خوانند در برابر آن بررسی کنند، یا انواع خود را از آن تولید کنند.

مثال‌ها

پاورشل (Windows):

$ep = Get-Content "$env:APPDATA\mattdownloadmanager\ipc.json" | ConvertFrom-Json
$client = New-Object Net.Sockets.TcpClient("127.0.0.1", $ep.port)
$stream = $client.GetStream()
$writer = New-Object IO.StreamWriter($stream); $reader = New-Object IO.StreamReader($stream)
$writer.WriteLine((@{ token = $ep.token; query = "list" } | ConvertTo-Json -Compress))
$writer.Flush()
$reader.ReadLine() | ConvertFrom-Json | Select-Object -ExpandProperty downloads | Format-Table file, status, downloaded, size
$client.Close()

پایتون:

import json, os, socket

ipc = os.path.join(os.environ["APPDATA"], "mattdownloadmanager", "ipc.json")  # see above elsewhere
ep = json.load(open(ipc))
with socket.create_connection(("127.0.0.1", ep["port"])) as s:
    s.sendall((json.dumps({"token": ep["token"], "query": "list"}) + "\n").encode())
    answer = json.loads(s.makefile().readline())
for d in answer["downloads"]:
    print(d["file"], d["status"], d["downloaded"], d["size"])

برای افزودن یک دانلود، {"token": "…", "url": "https://example.com/a.zip", "silent": true} را بفرستید.

رایگان، متن‌باز، بدون تبلیغات، بدون دوره آزمایشی.

بارگیری Matt Download Manager