getraw 0.1.0

package/STATUS.md

@@ -0,0 +1,23 @@
+# dlpx — Agent Status Board
+
+Last updated: 2026-06-16
+
+| # | Agent | Scope | Status | Notes |
+|---|-------|-------|--------|-------|
+| 1 | Scaffold | Project structure, types, core infra | DONE | Foundation complete |
+| 2 | YouTube Extractor | YouTube video/playlist extraction | DONE | InnerTube API, sig/nsig decipher, captions, playlists, age-gate bypass, 25 tests passing |
+| 3 | Twitter/X Extractor | Twitter/X video extraction | PENDING | |
+| 4 | Instagram Extractor | Instagram reels/stories/posts | PENDING | |
+| 5 | TikTok Extractor | TikTok video extraction | PENDING | |
+| 6 | Reddit Extractor | Reddit video/gallery extraction | PENDING | |
+| 7 | Twitch Extractor | Twitch VOD/clip extraction | PENDING | |
+| 8 | SoundCloud Extractor | SoundCloud audio extraction | PENDING | |
+| 9 | HLS Downloader | m3u8/HLS stream downloading | DONE | AES-128 decrypt, concurrent segments, master playlist variant selection |
+| 10 | DASH Downloader | MPD/DASH stream downloading | DONE | SegmentTemplate+SegmentList, multi-period, concurrent segments |
+| 11 | FFmpeg PostProcessor | Audio extract, merge, embed | PENDING | |
+| 12 | Subtitle PostProcessor | Subtitle download/convert/embed | PENDING | |
+| 13 | Networking | HTTP client, cookies, auth | PENDING | |
+| 14 | Plugins | Plugin loader and API | PENDING | |
+| 15 | Integration Tests | Cross-module integration tests | PENDING | |
+| 16 | E2E Tests | End-to-end download tests | PENDING | |
+| 17 | Polish & Release | CLI polish, README, binary build | PENDING | |

package/bun.lock

@@ -0,0 +1,50 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "dlpx",
+      "dependencies": {
+        "hls-parser": "^0.13.6",
+        "mpd-parser": "^1.3.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@babel/runtime": ["@babel/runtime@7.29.7", "", {}, "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw=="],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@25.9.3", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg=="],
+
+    "@videojs/vhs-utils": ["@videojs/vhs-utils@4.0.0", "", { "dependencies": { "@babel/runtime": "^7.12.5", "global": "^4.4.0", "url-toolkit": "^2.2.1" } }, "sha512-xJp7Yd4jMLwje2vHCUmi8MOUU76nxiwII3z4Eg3Ucb+6rrkFVGosrXlMgGnaLjq724j3wzNElRZ71D/CKrTtxg=="],
+
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.13", "", {}, "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "dom-walk": ["dom-walk@0.1.2", "", {}, "sha512-6QvTW9mrGeIegrFXdtQi9pk7O/nSK6lSdXW2eqUspN5LWD7UTji2Fqw5V2YLjBpHEoU9Xl/eUWNpDeZvoyOv2w=="],
+
+    "global": ["global@4.4.0", "", { "dependencies": { "min-document": "^2.19.0", "process": "^0.11.10" } }, "sha512-wv/LAoHdRE3BeTGz53FAamhGlPLhlssK45usmGFThIi4XqnBmjKQ16u+RNbP7WvigRZDxUsM0J3gcQ5yicaL0w=="],
+
+    "hls-parser": ["hls-parser@0.13.6", "", {}, "sha512-I40sl22E2muqeSTpG8kMN2dAegAhubkXPXtnsUXFwdKwZK47d1Q+XwuX32VMZ++AZU5oeQIZqAnGNHxSG1sWaw=="],
+
+    "min-document": ["min-document@2.19.2", "", { "dependencies": { "dom-walk": "^0.1.0" } }, "sha512-8S5I8db/uZN8r9HSLFVWPdJCvYOejMcEC82VIzNUc6Zkklf/d1gg2psfE79/vyhWOj4+J8MtwmoOz3TmvaGu5A=="],
+
+    "mpd-parser": ["mpd-parser@1.3.1", "", { "dependencies": { "@babel/runtime": "^7.12.5", "@videojs/vhs-utils": "^4.0.0", "@xmldom/xmldom": "^0.8.3", "global": "^4.4.0" }, "bin": { "mpd-to-m3u8-json": "bin/parse.js" } }, "sha512-1FuyEWI5k2HcmhS1HkKnUAQV7yFPfXPht2DnRRGtoiiAAW+ESTbtEXIDpRkwdU+XyrQuwrIym7UkoPKsZ0SyFw=="],
+
+    "process": ["process@0.11.10", "", {}, "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "url-toolkit": ["url-toolkit@2.2.5", "", {}, "sha512-mtN6xk+Nac+oyJ/PrI7tzfmomRVNFIWKUbG8jdYFt52hxbiReFAXIjYskvu64/dvuW71IcB7lV8l0HvZMac6Jg=="],
+  }
+}

package/bunfig.toml

@@ -0,0 +1,3 @@
+[test]
+coverage = true
+coverageDir = "coverage"

package/docs/plugin-guide.md

@@ -0,0 +1,166 @@
+# Plugin Guide — Writing a Custom Extractor
+
+dlpx extractors are classes that extend `BaseExtractor` from `src/core/types.ts`. Once written, they are registered via `registerExtractor` from `src/extractors/base.ts`. dlpx then tries each registered extractor in order before falling back to the generic extractor.
+
+## BaseExtractor Interface
+
+```ts
+// src/core/types.ts
+
+export abstract class BaseExtractor {
+  // Regex tested against the URL to decide if this extractor handles it.
+  abstract readonly _VALID_URL: RegExp;
+
+  // Human-readable name used in logs and the extractor field of InfoDict.
+  abstract readonly _NAME: string;
+
+  // Returns true when _VALID_URL matches the URL. Override to add custom logic.
+  canHandle(url: string): boolean {
+    return this._VALID_URL.test(url);
+  }
+
+  // Public entry point. Calls _real_extract and stamps extractor metadata.
+  async extract(url: string): Promise<InfoDict> { ... }
+
+  // Your implementation goes here.
+  protected abstract _real_extract(url: string): Promise<InfoDict>;
+}
+```
+
+`_real_extract` must return an `InfoDict`. The key fields are:
+
+```ts
+interface InfoDict {
+  id: string;           // required — unique ID for the media
+  title: string;        // required
+  formats?: Format[];   // list of available streams; mutually exclusive with url
+  url?: string;         // use this if there is exactly one stream URL
+  ext?: string;         // file extension when using url
+  thumbnails?: Thumbnail[];
+  subtitles?: Record<string, Subtitle[]>;
+  automatic_captions?: Record<string, Subtitle[]>;
+  description?: string;
+  uploader?: string;
+  duration?: number;    // seconds
+  // ... see src/core/types.ts for the full list
+}
+```
+
+Each `Format` describes one downloadable stream:
+
+```ts
+interface Format {
+  format_id: string;    // required
+  url: string;          // required
+  ext: string;          // required — e.g. "mp4", "m4a", "webm"
+  protocol?: string;    // "https", "m3u8", "dash" — controls which downloader is used
+  width?: number;
+  height?: number;
+  fps?: number;
+  vcodec?: string;      // "avc1.…", "vp9", "none" (audio-only)
+  acodec?: string;      // "mp4a.…", "opus", "none" (video-only)
+  vbr?: number;         // video bitrate kbps
+  abr?: number;         // audio bitrate kbps
+  tbr?: number;         // total bitrate kbps
+  filesize?: number;
+  http_headers?: Record<string, string>;
+}
+```
+
+## Minimal Example
+
+```ts
+// src/extractors/example.ts
+
+import { BaseExtractor, ExtractorError } from "../core/types";
+import type { InfoDict } from "../core/types";
+
+export class ExampleExtractor extends BaseExtractor {
+  readonly _VALID_URL = /https?:\/\/(?:www\.)?example\.com\/watch\/([a-zA-Z0-9]+)/;
+  readonly _NAME = "example";
+
+  protected async _real_extract(url: string): Promise<InfoDict> {
+    const match = this._VALID_URL.exec(url);
+    if (!match) throw new ExtractorError(`example: invalid URL: ${url}`);
+    const videoId = match[1];
+
+    // Fetch the page or an API endpoint to find the stream URL.
+    const apiUrl = `https://example.com/api/videos/${videoId}`;
+    const resp = await fetch(apiUrl, {
+      headers: { "User-Agent": "Mozilla/5.0" },
+    });
+    if (!resp.ok) {
+      throw new ExtractorError(`example: API returned ${resp.status}`);
+    }
+
+    const data = (await resp.json()) as {
+      title: string;
+      mp4_url: string;
+      duration_s: number;
+    };
+
+    return {
+      id: videoId,
+      title: data.title,
+      url: data.mp4_url,
+      ext: "mp4",
+      duration: data.duration_s,
+      extractor: this._NAME,
+    };
+  }
+}
+```
+
+If the site provides multiple quality levels, return them as `formats` instead of a single `url`:
+
+```ts
+return {
+  id: videoId,
+  title: data.title,
+  formats: [
+    {
+      format_id: "1080p",
+      url: data.hd_url,
+      ext: "mp4",
+      width: 1920,
+      height: 1080,
+      vcodec: "avc1",
+      acodec: "mp4a",
+    },
+    {
+      format_id: "480p",
+      url: data.sd_url,
+      ext: "mp4",
+      width: 854,
+      height: 480,
+      vcodec: "avc1",
+      acodec: "mp4a",
+    },
+  ],
+};
+```
+
+## Registering the Extractor
+
+Import `registerExtractor` from `src/extractors/base.ts` and call it before the orchestrator runs. The standard place is an index file that is imported by the entry point:
+
+```ts
+// src/extractors/index.ts  (or wherever you collect registrations)
+
+import { registerExtractor } from "./base";
+import { ExampleExtractor } from "./example";
+
+registerExtractor(new ExampleExtractor());
+```
+
+Extractors are tested in registration order. Place more-specific extractors before broader ones. The `generic` extractor is always the last fallback and cannot be displaced.
+
+## Error Handling
+
+Throw `ExtractorError` (from `src/core/types.ts`) for expected failures (unsupported URL shape, API error, content not found). Any other thrown error is automatically wrapped in an `ExtractorError` by the base class before propagating.
+
+```ts
+import { ExtractorError } from "../core/types";
+
+throw new ExtractorError("example: video is private");
+```

package/docs/supported-sites.md

@@ -0,0 +1,41 @@
+# Supported Sites
+
+All extractors implement `BaseExtractor` from `src/core/types.ts`. The `_VALID_URL` regex for each is listed below — dlpx tests URLs against these in registration order, falling back to the `generic` extractor for any `http(s)://` URL.
+
+| # | Extractor name | Site | URL pattern | Formats | Notes |
+|---|---------------|------|-------------|---------|-------|
+| 1 | `youtube` | YouTube | `(www\|m\|music).youtube.com/watch?v=`, `youtu.be/<id>`, `youtube.com/shorts/<id>`, `youtube.com/live/<id>`, `youtube.com/embed/<id>`, `youtube.com/v/<id>`, `youtube.com/playlist?list=`, `youtube.com/channel/<id>`, `youtube.com/@<handle>` | DASH (MP4 video + M4A audio), HLS | Subtitles (manual) and auto-generated captions extracted. Age-gated videos attempt TV client bypass. Signature and n-sig deciphering implemented. Playlist and channel enumeration supported. |
+| 2 | `vimeo` | Vimeo | `(www\|player).vimeo.com/<id>`, `vimeo.com/channels/<c>/<id>`, `vimeo.com/groups/<g>/videos/<id>` | HLS, DASH, Progressive MP4 | All CDN variants exposed as separate formats. |
+| 3 | `twitter` | Twitter / X | `(www.)twitter.com/<user>/status/<id>`, `(www.)x.com/<user>/status/<id>` | MP4 (multiple bitrates), HLS | Uses the public syndication API — no auth required. |
+| 4 | `twitter:spaces` | Twitter Spaces | `(www.)twitter.com/i/spaces/<id>`, `(www.)x.com/i/spaces/<id>` | HLS (M3U8) | Uses a guest token obtained from the public API. Spaces must be public. |
+| 5 | `tiktok` | TikTok video | `(www.)tiktok.com/@<user>/video/<id>`, `vm.tiktok.com/<id>` | MP4 (playAddr / downloadAddr) | Parses hydration JSON embedded in the page HTML. |
+| 6 | `tiktok:user` | TikTok user feed | `(www.)tiktok.com/@<username>` | Playlist (entries) | Returns a playlist of video URLs from the user's public profile page. |
+| 7 | `instagram` | Instagram post / reel | `(www.)instagram.com/p/<id>`, `instagram.com/reel/<id>`, `instagram.com/reels/<id>` | MP4 | Parses `__additionalDataLoaded` and `window.__additionalData` from page. Sidecar (multi-image) posts extracted as playlist. |
+| 8 | `instagram:reels` | Instagram Reels feed | `(www.)instagram.com/reels/` | MP4 | Fetches via the internal GraphQL endpoint (`PolarisClipsHomePageQuery`). Returns a playlist. |
+| 9 | `twitch:vod` | Twitch VOD | `(www.)twitch.tv/videos/<id>` | HLS (M3U8, multiple quality levels) | Uses Twitch GQL to get a signed playback access token. |
+| 10 | `twitch:clip` | Twitch Clip | `(www.)twitch.tv/<channel>/clip/<slug>`, `clips.twitch.tv/<slug>` | MP4 (multiple quality levels) | Signed MP4 URLs fetched via GQL. |
+| 11 | `twitch:live` | Twitch Live stream | `(www.)twitch.tv/<channel>` | HLS (M3U8, multiple quality levels) | Errors if channel is offline. Signed via GQL stream playback access token. |
+| 12 | `kick` | Kick VOD | `(www.)kick.com/video/<id>` | HLS (M3U8) | Uses the Kick v1 public API. |
+| 13 | `kick:clips` | Kick Clip | `(www.)kick.com/<channel>/clips/<id>` | MP4 | Uses the Kick v1 clips API. |
+| 14 | `kick:live` | Kick Live stream | `(www.)kick.com/<channel>` | HLS (M3U8) | Errors if channel is not live. |
+| 15 | `reddit` | Reddit video post | `(www.\|old.)reddit.com/r/<sub>/comments/<id>`, `v.redd.it/<id>` | DASH (video) + separate audio URL, MP4 fallback | Audio is extracted from the DASH manifest and presented as a separate format so both can be merged. |
+| 16 | `reddit:gallery` | Reddit gallery post | `(www.\|old.)reddit.com/r/<sub>/comments/<id>`, `reddit.com/gallery/<id>` | Images (JPEG/PNG) and MP4 (gallery items) | Each gallery item is returned as a separate entry in a playlist. |
+| 17 | `soundcloud` | SoundCloud track | `(www.\|m.)soundcloud.com/<user>/<track>` | HLS (M3U8 opus/mp3), HTTP progressive MP3 | client_id is extracted dynamically from the JS bundle. |
+| 18 | `soundcloud:playlist` | SoundCloud set / playlist | `(www.\|m.)soundcloud.com/<user>/sets/<playlist>` | Playlist (entries) | Paginates via `api-v2.soundcloud.com/playlists/<id>/tracks`. |
+| 19 | `bilibili` | Bilibili video | `(www.)bilibili.com/video/BV<id>`, `bilibili.com/video/av<id>` | DASH (video + audio, multiple quality levels from 360p to 8K/HDR/Dolby) | Requires login cookies for 1080p+ qualities. BV-to-AV ID conversion implemented. |
+| 20 | `bilibili:bangumi` | Bilibili Bangumi (anime/series) | `(www.)bilibili.com/bangumi/play/ep<id>`, `bilibili.com/bangumi/play/ss<id>` | DASH (same quality levels as bilibili) | `ep_id` fetches a single episode; `ss_id` fetches the full season as a playlist. |
+| 21 | `niconico` | Niconico | `(www.)nicovideo.jp/watch/sm<id>`, `nicovideo.jp/watch/nm<id>` | HLS (DMS session-based M3U8) | Session cookies from the watch page are forwarded to the DMS API. |
+| 22 | `bandcamp` | Bandcamp track / album | `<artist>.bandcamp.com/track/<slug>`, `<artist>.bandcamp.com/album/<slug>`, `bandcamp.com/EmbeddedPlayer/*` | MP3 (stream URL from `trackinfo` JSON) | Album URLs return a playlist of tracks. |
+| 23 | `dailymotion` | Dailymotion | `(www.)dailymotion.com/video/<id>` | HLS (M3U8) | Uses the Dailymotion player metadata API. |
+| 24 | `streamable` | Streamable | `(www.)streamable.com/<id>` | MP4 (multiple resolutions), HLS | Parses the player JSON from `api.streamable.com/videos/<id>`. |
+| 25 | `coub` | Coub | `(www.)coub.com/view/<id>`, `coub.com/embed/<id>` | MP4 (video), MP3 (audio), GIF | Video loop and audio are separate; both formats are exposed. |
+| 26 | `imgur` | Imgur | `imgur.com/<id>`, `imgur.com/a/<id>` (album), `imgur.com/gallery/<id>`, `i.imgur.com/<id>.<ext>` | MP4, GIF (converted), JPEG/PNG | Direct image/video links, single items, and albums all handled. Albums return a playlist. |
+| 27 | `rumble` | Rumble | `(www.)rumble.com/v<slug>.html`, `rumble.com/embed/<id>` | MP4 (multiple resolutions) | Parses the embedded player JSON. |
+| 28 | `odysee` | Odysee / LBRY | `(www.)odysee.com/@<channel>:<tag>/<slug>`, `lbry.tv/@<channel>:<tag>/<slug>` | MP4, HLS (if present) | Uses the Odysee API v3 to resolve claim URLs. |
+| 29 | `ted` | TED Talks | `(www.)ted.com/talks/<slug>` | MP4 (multiple qualities via `playerData.resources.h264`) | Subtitles extracted from `subtitledDownloads` (SRT). |
+| 30 | `peertube` | PeerTube (any instance) | `<host>/videos/watch/<uuid>`, `<host>/w/<uuid>`, `<host>/videos/embed/<uuid>` | WebTorrent (MP4), HLS | Subtitles (VTT) extracted from the captions API. Works with any PeerTube instance. |
+| 31 | `google-drive` | Google Drive | `drive.google.com/file/d/<id>`, `docs.google.com/file/d/<id>`, `drive.google.com/uc?id=<id>` | MP4 (itag-based URLs) | Public files only. Parses the Drive streaming page for itag format entries. |
+| 32 | `dropbox` | Dropbox | `(www.)dropbox.com/s/<id>`, `dropbox.com/sh/<id>`, `dropbox.com/scl/fo/<id>` | Direct download URL (any type) | Rewrites the `dl=0` query parameter to `dl=1` for direct download. |
+| 33 | `archive.org` | Internet Archive | `(www.)archive.org/details/<id>`, `archive.org/download/<id>` | MP4, OGV, WEBM, MP3, and any other files hosted on the item | All media files listed under the item are returned as formats. |
+| 34 | `spotify` | Spotify Podcast | `open.spotify.com/episode/<id>` | MP3 (30-second preview only) | Full episode audio requires Spotify auth, which is not implemented. Preview URL is from `previewUrl` in the episode API. |
+| 35 | `generic` | Generic fallback | Any `http://` or `https://` URL | Depends on the target | Fetches the page and looks for `<video src>`, `<source src>`, and `og:video` meta tags. Last resort. |

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "getraw",
+  "version": "0.1.0",
+  "description": "Fast media downloader CLI built natively in Bun/TypeScript",
+  "type": "module",
+  "bin": {
+    "dlpx": "./src/cli/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/cli/index.ts",
+    "test": "bun test",
+    "build": "bun build src/cli/index.ts --compile --outfile=dlpx",
+    "dashboard": "bun run tools/dashboard.ts"
+  },
+  "dependencies": {
+    "hls-parser": "^0.13.6",
+    "mpd-parser": "^1.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/web3mikee/dlpx"
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+import { parseArgs, printHelp } from "./options";
+import { Orchestrator } from "../core/orchestrator";
+import { logger } from "../core/logger";
+
+const VERSION = "0.0.0";
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+
+  if (options.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (options.version) {
+    process.stdout.write(`dlpx ${VERSION}\n`);
+    process.exit(0);
+  }
+
+  if (options.verbose) {
+    logger.setLevel("debug");
+  }
+
+  if (options.quiet) {
+    logger.setQuiet(true);
+  }
+
+  if (options.urls.length === 0) {
+    logger.error("No URLs provided. Use --help for usage.");
+    process.exit(1);
+  }
+
+  const orchestrator = new Orchestrator();
+
+  for (const url of options.urls) {
+    try {
+      await orchestrator.process(url, options);
+    } catch (err) {
+      logger.error(
+        err instanceof Error ? err.message : String(err),
+      );
+      if (options.verbose && err instanceof Error && err.stack) {
+        logger.debug(err.stack);
+      }
+      process.exit(1);
+    }
+  }
+}
+
+main();

package/src/cli/options.ts

@@ -0,0 +1,97 @@
+import type { Options } from "../core/types";
+import { DEFAULT_OPTIONS } from "../core/types";
+
+interface FlagDef {
+  long: string;
+  short?: string;
+  description: string;
+  type: "boolean" | "string" | "number";
+  key: keyof Options;
+}
+
+export const FLAG_DEFS: FlagDef[] = [
+  { long: "--format", short: "-f", description: "Format selection string", type: "string", key: "format" },
+  { long: "--output", short: "-o", description: "Output filename template", type: "string", key: "output" },
+  { long: "--extract-audio", short: "-x", description: "Extract audio only", type: "boolean", key: "extractAudio" },
+  { long: "--audio-format", description: "Audio format (mp3, aac, flac, etc.)", type: "string", key: "audioFormat" },
+  { long: "--audio-quality", description: "Audio quality (0-10 or bitrate)", type: "string", key: "audioQuality" },
+  { long: "--write-subs", description: "Write subtitles to file", type: "boolean", key: "writeSubs" },
+  { long: "--sub-langs", description: "Subtitle languages", type: "string", key: "subLangs" },
+  { long: "--list-formats", short: "-F", description: "List available formats", type: "boolean", key: "listFormats" },
+  { long: "--dump-json", short: "-j", description: "Dump info JSON to stdout", type: "boolean", key: "dumpJson" },
+  { long: "--quiet", short: "-q", description: "Suppress output", type: "boolean", key: "quiet" },
+  { long: "--verbose", short: "-v", description: "Verbose output", type: "boolean", key: "verbose" },
+  { long: "--no-progress", description: "Disable progress bar", type: "boolean", key: "noProgress" },
+  { long: "--retries", short: "-R", description: "Number of retries", type: "number", key: "retries" },
+  { long: "--rate-limit", short: "-r", description: "Rate limit in bytes/sec", type: "number", key: "rateLimit" },
+  { long: "--proxy", description: "Proxy URL", type: "string", key: "proxy" },
+  { long: "--cookies", description: "Cookie file path", type: "string", key: "cookies" },
+  { long: "--user-agent", description: "Custom User-Agent", type: "string", key: "userAgent" },
+  { long: "--referer", description: "Custom Referer", type: "string", key: "referer" },
+  { long: "--embed-thumbnail", description: "Embed thumbnail in output", type: "boolean", key: "embedThumbnail" },
+  { long: "--embed-subs", description: "Embed subtitles in output", type: "boolean", key: "embedSubs" },
+  { long: "--merge-output-format", description: "Output container for merging", type: "string", key: "mergeOutputFormat" },
+  { long: "--ffmpeg-location", description: "Path to ffmpeg binary", type: "string", key: "ffmpegLocation" },
+  { long: "--version", short: "-V", description: "Print version", type: "boolean", key: "version" },
+  { long: "--help", short: "-h", description: "Show help", type: "boolean", key: "help" },
+];
+
+export function parseArgs(args: string[]): Options {
+  const options: Options = { ...DEFAULT_OPTIONS, paths: { ...DEFAULT_OPTIONS.paths }, urls: [] };
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (!arg.startsWith("-")) {
+      options.urls.push(arg);
+      i++;
+      continue;
+    }
+
+    const def = FLAG_DEFS.find((d) => d.long === arg || d.short === arg);
+
+    if (!def) {
+      options.urls.push(arg);
+      i++;
+      continue;
+    }
+
+    if (def.type === "boolean") {
+      (options as Record<string, unknown>)[def.key] = true;
+      i++;
+      continue;
+    }
+
+    const value = args[i + 1];
+    if (value === undefined) {
+      throw new Error(`Missing value for ${arg}`);
+    }
+
+    if (def.type === "number") {
+      (options as Record<string, unknown>)[def.key] = Number(value);
+    } else {
+      (options as Record<string, unknown>)[def.key] = value;
+    }
+    i += 2;
+  }
+
+  return options;
+}
+
+export function printHelp(): void {
+  const lines = [
+    "dlpx — Fast media downloader",
+    "",
+    "Usage: dlpx [OPTIONS] URL [URL...]",
+    "",
+    "Options:",
+  ];
+
+  for (const def of FLAG_DEFS) {
+    const flags = def.short ? `${def.short}, ${def.long}` : `    ${def.long}`;
+    lines.push(`  ${flags.padEnd(28)} ${def.description}`);
+  }
+
+  process.stdout.write(lines.join("\n") + "\n");
+}