Skip to content

Latest commit

 

History

History
89 lines (65 loc) · 7 KB

usage.md

File metadata and controls

89 lines (65 loc) · 7 KB

Usage

Desktop Suite after installation. Phone / Quest: android.md, quest.md. Companion ↔ Suite: cross-platform.md.

Launch

.venv/bin/python main.py
# or: ./run.sh
# Linux menu/PATH after ./scripts/install_local.sh:
# ytsdownloader

Classic tabbed UI:

.venv/bin/python main.py --legacy

Frozen onedir build (from the shipped folder, writable cwd for .ytsdownloader/):

cd dist/YTSDownloader
./YTSDownloader
cd dist\YTSDownloader
.\YTSDownloader.exe

Optional activation: bash/zsh source .venv/bin/activate, fish source .venv/bin/activate.fish.

After install (Desktop Suite)

  1. Ensure ffmpeg / ffprobe work: ffmpeg -version and ffprobe -version.
  2. Launch the Suite (commands above). Sidebar: Download, Queue, Link Grabber, Metadata Bridge, Settings.
  3. Open Settings if you need cookies (COOKIES_FROM_BROWSER or COOKIES_FILE), workers, pace, or default output — Save writes config.ini.
  4. On Download: set output folder, choose Export preset (Audio only / Video + audio / Watermark / Custom), paste or drop a URL → Resolve & Queue → Start Queue.
  5. Open Queue to filter by state/search, triage failures, Retry selected / Retry failed, or right-click Force download.
  6. Optional companions: keep Suite open while Android/Quest Export to Downloads JSON lands in .ytsdownloader/inbox/ (poll ~1.5 s) — cross-platform.md.

Suite flow (detail)

  1. Open Download, set an output folder, paste a URL, or drop links onto the drop zone (a single URL fills the field; multiple URLs crawl into the queue).
  2. Choose an Export preset (Audio only, Video + audio, Watermark, or Custom). Presets set media / container / watermark for new jobs; Watermark requires a PNG path.
  3. Optionally set Crawl mode and Limit (1–10000, or 0 / Unlimited). Shallow is a single-pass resolve. Deep / Videos / Shorts / Posts need cookie auth (COOKIES_FROM_BROWSER or COOKIES_FILE) and only enumerate content your signed-in session can already reach — no paywall or DRM bypass. Adult-tube model/user Deep mode paces videos, uploads, GIFs, and albums (album → photos); Shorts = GIF listings; Posts = album/photo listings.
  4. File options on Download (also under Settings → SKIP_EXISTING / OVERWRITE / NUMBER_FILES): Skip existing files (default on) avoids re-downloading ids already present in the output folder or .yts_download_archive.txt; Overwrite forces a fresh download (wins over skip); Number files in queue toggles the 0001_ filename prefix.
  5. Resolve & Queue, then open Queue and press Start (or use Start Queue on Download).
  6. Filter the queue by State and/or Search (title, URL, message, export label).
  7. Optionally pick a preset on Queue and Apply to selected rows or Apply to queued items (metadata-bridge search-audio jobs are left unchanged).
  8. When items fail, select a row in the Failure triage panel to see the classified category and full error; use Retry selected or Retry failed (preserves URL / export options; press Start if the queue is paused). Right-click a row for Remove from queue or Force download (starts that item immediately, skipping pace wait, even if the queue is stopped).
  9. Use Link Grabber to paste many URLs (one per line); enqueue uses the Download page preset and crawl mode / limit.
  10. Optional: a browser companion, Android phone, or Quest panel can drop URLs into .ytsdownloader/inbox/ or append NDJSON to .ytsdownloader/companion_inbox.jsonl while the Suite is open — the desktop app remains the downloader (cross-platform.md, Architecture).
  11. Use Metadata Bridge while a desktop music client is playing to queue a matching public-host audio download.
  12. Use Settings to edit and Save config.ini (cookies, pace, backoff, workers, formats, skip/overwrite/numbering, status analytics); most knobs apply without restarting the app.
  13. Watch per-item progress on the Queue page (Export column shows audio / video / video+wm). Large queues show one filtered page (Prev/Next); the status line still reports full done/total counts. With Show analytics in status bar enabled (default), the status bar shows local session OK / Err counts plus Last and Avg job durations — nothing is sent over the network.

Queue persistence

The Suite saves the download queue to .ytsdownloader/queue_state.json (gitignored) when items are enqueued, change state, you clear finished / clear all, or the app closes. Large queues debounce and compact that write so the UI stays responsive.

On the next launch the queue is restored (table shows the first filtered page). Items that were running come back as queued with a resume hint — downloads are not auto-started. Press Start when you are ready.

Clear Finished removes done / failed / cancelled jobs from both the table and the saved file. Clear All asks for confirmation, then removes every item and persists the empty queue.

On Linux, Browse for the output folder (Download page and Settings default output) opens a Qt dialog whose sidebar lists the local system root (Computer / /) plus mounted volumes under /run/media/$USER, /media/$USER, and real /mnt mounts. Standard places such as Desktop, Documents, Downloads, and Trash are omitted.

Platform URL patterns

  • YouTube channel: https://www.youtube.com/@channelname
  • YouTube video / Short / playlist URLs
  • Instagram profile / reel / post URLs
  • Facebook page / post / watch URLs
  • TikTok profile / video URLs
  • Adult-tube video / playlist / model URLs (private / unlisted playlists need cookies; Deep crawl enumerates videos / GIFs / albums when cookies are set)
  • Adult video host (rule34video.com class): single videos, latest/top feeds, tags, members, search — paste into Download URL; Deep / Videos crawl paginates listings (cookies recommended for age-gated or restricted surfaces)
  • Creator / gallery / clip hosts (creator_media): ManyVids, RedGifs, Vimeo, VK, Reddit, Twitter/X via yt-dlp when the extractor works; Clips4Sale / Aryion favorites + gallery-class hosts via clean-room HTML harvest and public preview/CDN rewrite (Aryion listings paginate all ?p= pages under Deep/Videos or Unlimited; singles use data.php originals for every item type; cookies for purchased or restricted surfaces your session can already open)
  • Catalog track / playlist / album URLs for the metadata bridge

Auth check

Use Check Auth after entering a URL to validate cookie / JS runtime extraction without starting a full batch.

Outputs

  • Media files land in the selected folder
  • Optional watermark PNG composites when configured
  • Queue spaces playlist/job starts by COUNT_TIMER_ONGOING and retries failed items up to MAX_RETRIES with exponential backoff (BACKOFF_*; harder on HTTP 429)