yt-dlp-bridge 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +64 -165
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -4,39 +4,22 @@
4
4
  [![npm downloads](https://img.shields.io/npm/dm/yt-dlp-bridge.svg)](https://www.npmjs.com/package/yt-dlp-bridge)
5
5
  [![CI](https://github.com/antonio-orionus/yt-dlp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/antonio-orionus/yt-dlp-bridge/actions/workflows/ci.yml)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
- [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
8
- [![Node.js >=22.13](https://img.shields.io/badge/node-%3E%3D22.13-brightgreen.svg)](package.json)
9
7
 
10
- TypeScript primitives for building safe, policy-aware integrations on top of `yt-dlp`: command planning, argv generation, environment checks, process execution, output parsing, redaction, and structured errors.
8
+ TypeScript library for safe, no-shell `yt-dlp` integration in Node.js services: policy-aware command planning, argv generation, environment checks, process execution, output parsing, secret redaction, and structured errors.
11
9
 
12
- `yt-dlp-bridge` is intentionally MCP-agnostic. It is the integration layer used by `yt-dlp-mcp-server`, but it can be used anywhere a Node.js service needs to plan or run `yt-dlp` without shell interpolation.
13
-
14
- ## Contents
10
+ `yt-dlp-bridge` is intentionally MCP-agnostic. It is the integration layer used by `yt-dlp-mcp-server`, but it works anywhere a Node.js service needs to plan or run `yt-dlp` without shell interpolation.
15
11
 
12
+ - [Install](#install)
16
13
  - [Features](#features)
17
- - [Quick Start](#quick-start)
18
- - [Installation](#installation)
19
14
  - [Usage](#usage)
20
- - [API Surface](#api-surface)
15
+ - [API](#api)
21
16
  - [Configuration](#configuration)
22
17
  - [Requirements](#requirements)
23
18
  - [Development](#development)
24
- - [Release](#release)
25
19
  - [Troubleshooting](#troubleshooting)
26
20
  - [License](#license)
27
21
 
28
- ## Features
29
-
30
- - Source-derived option catalog generated from `yt_dlp.options.create_parser`.
31
- - Safe argv builders that return argument arrays instead of shell command strings.
32
- - Dependency-aware download and post-processing plans for `yt-dlp`, `ffmpeg`, `ffprobe`, external downloaders, browser impersonation, and JavaScript runtimes.
33
- - Managed output policy for output roots, temp roots, archive files, overwrite behavior, and parent-directory traversal checks.
34
- - Secret redaction for auth flags, cookies, signed URLs, and command previews.
35
- - Parsers for JSON lines, format lists, subtitle lists, thumbnail lists, progress output, and final output paths.
36
- - Structured error adaptation through [`ytdlp-errors`](https://www.npmjs.com/package/ytdlp-errors).
37
- - ESM and TypeScript declarations out of the box.
38
-
39
- ## Quick Start
22
+ ## Install
40
23
 
41
24
  ```bash
42
25
  npm install yt-dlp-bridge
@@ -45,53 +28,38 @@ npm install yt-dlp-bridge
45
28
  # bun add yt-dlp-bridge
46
29
  ```
47
30
 
31
+ Requires Node.js >= 22.13 and ESM.
32
+
48
33
  ```ts
49
- import {
50
- PlanDownloadInputSchema,
51
- loadConfig,
52
- planDownload
53
- } from "yt-dlp-bridge";
34
+ import { PlanDownloadInputSchema, loadConfig, planDownload } from "yt-dlp-bridge";
54
35
 
55
36
  const config = loadConfig();
56
37
  const input = PlanDownloadInputSchema.parse({
57
38
  url: "https://www.youtube.com/watch?v=BaW_jenozKc",
58
39
  kind: "audio",
59
- postprocess: {
60
- audioFormat: "mp3"
61
- },
62
- output: {
63
- outputRoot: "audio"
64
- }
40
+ postprocess: { audioFormat: "mp3" },
41
+ output: { outputRoot: "audio" }
65
42
  });
66
43
 
67
44
  const plan = await planDownload(input, config);
68
-
69
- console.log(plan.commandPreview.command);
70
45
  console.log(plan.commandPreview.redactedArgs);
71
46
  console.log(plan.requiredDependencies);
72
47
  ```
73
48
 
74
- ## Installation
75
-
76
- For package consumers:
77
-
78
- ```bash
79
- npm install yt-dlp-bridge
80
- ```
81
-
82
- For source development, this repository uses pnpm:
49
+ ## Features
83
50
 
84
- ```bash
85
- git clone https://github.com/antonio-orionus/yt-dlp-bridge.git
86
- cd yt-dlp-bridge
87
- pnpm install
88
- pnpm run build
89
- pnpm test
90
- ```
51
+ - Source-derived option catalog generated from `yt_dlp.options.create_parser`.
52
+ - Safe argv builders that return argument arrays instead of shell command strings.
53
+ - Dependency-aware download and post-processing plans for `yt-dlp`, `ffmpeg`, `ffprobe`, external downloaders, browser impersonation, and JavaScript runtimes.
54
+ - Managed output policy for output roots, temp roots, archive files, overwrite behavior, and parent-directory traversal checks.
55
+ - Secret redaction for auth flags, cookies, signed URLs, and command previews.
56
+ - Parsers for JSON lines, format lists, subtitle lists, thumbnail lists, progress output, and final output paths.
57
+ - Structured error adaptation through [`ytdlp-errors`](https://www.npmjs.com/package/ytdlp-errors).
58
+ - ESM and TypeScript declarations.
91
59
 
92
60
  ## Usage
93
61
 
94
- ### Build Inspect Arguments
62
+ ### Inspect metadata
95
63
 
96
64
  Use the Zod schemas to fill defaults before passing inputs into the low-level builders.
97
65
 
@@ -101,69 +69,47 @@ import { InspectInputSchema, buildMetadataArgs } from "yt-dlp-bridge";
101
69
  const input = InspectInputSchema.parse({
102
70
  url: "https://www.youtube.com/watch?v=BaW_jenozKc"
103
71
  });
104
-
105
72
  const args = buildMetadataArgs(input);
106
-
107
- console.log(args);
108
73
  // ["--ignore-config", "--no-warnings", "--dump-json", "https://www.youtube.com/watch?v=BaW_jenozKc"]
109
74
  ```
110
75
 
111
- ### Plan a Download
76
+ ### Plan a download
112
77
 
113
78
  `planDownload` resolves output policy, builds the final argv, redacts secrets, checks available dependencies, and explains risks and side effects before anything is downloaded.
114
79
 
115
80
  ```ts
116
- import {
117
- PlanDownloadInputSchema,
118
- loadConfig,
119
- planDownload
120
- } from "yt-dlp-bridge";
81
+ import { PlanDownloadInputSchema, loadConfig, planDownload } from "yt-dlp-bridge";
121
82
 
122
83
  const config = loadConfig({
123
84
  YTDLP_MCP_OUTPUT_ROOT: "/srv/downloads",
124
85
  YTDLP_MCP_TEMP_ROOT: "/srv/downloads/.tmp"
125
86
  });
126
-
127
87
  const input = PlanDownloadInputSchema.parse({
128
88
  url: "https://www.youtube.com/watch?v=BaW_jenozKc",
129
89
  kind: "video",
130
- selection: {
131
- downloadArchive: "archive.txt"
132
- },
133
- format: {
134
- format: "bv*+ba/b"
135
- },
136
- output: {
137
- outputTemplate: "%(playlist_index)s-%(title).180B [%(id)s].%(ext)s"
138
- }
90
+ selection: { downloadArchive: "archive.txt" },
91
+ format: { format: "bv*+ba/b" },
92
+ output: { outputTemplate: "%(playlist_index)s-%(title).180B [%(id)s].%(ext)s" }
139
93
  });
140
94
 
141
95
  const plan = await planDownload(input, config);
142
-
143
96
  console.log(plan.argv);
144
97
  console.log(plan.risks);
145
98
  console.log(plan.sideEffects);
146
99
  ```
147
100
 
148
- ### Run a Planned Command
101
+ ### Run a planned command
149
102
 
150
103
  The runner uses `spawn` with `shell: false`, bounded output capture, timeouts, and structured failures.
151
104
 
152
105
  ```ts
153
- import {
154
- PlanDownloadInputSchema,
155
- loadConfig,
156
- planDownload,
157
- runCommand,
158
- toStructuredError
159
- } from "yt-dlp-bridge";
106
+ import { PlanDownloadInputSchema, loadConfig, planDownload, runCommand, toStructuredError } from "yt-dlp-bridge";
160
107
 
161
108
  const config = loadConfig();
162
109
  const input = PlanDownloadInputSchema.parse({
163
110
  url: "https://www.youtube.com/watch?v=BaW_jenozKc",
164
111
  kind: "video"
165
112
  });
166
-
167
113
  const plan = await planDownload(input, config);
168
114
 
169
115
  try {
@@ -171,143 +117,96 @@ try {
171
117
  timeoutMs: config.defaultTimeoutMs,
172
118
  maxOutputBytes: config.maxOutputBytes
173
119
  });
174
-
175
120
  console.log(result.stdout);
176
121
  } catch (error) {
177
122
  console.error(toStructuredError(error));
178
123
  }
179
124
  ```
180
125
 
181
- ### Inspect the Option Catalog
126
+ ### Query the option catalog
182
127
 
183
- The bundled catalog in this release is generated from `yt_dlp.options.create_parser` for yt-dlp `2026.03.17` and contains 323 upstream options.
128
+ The bundled catalog is generated from `yt_dlp.options.create_parser` for yt-dlp `2026.03.17` and contains 323 upstream options.
184
129
 
185
130
  ```ts
186
- import {
187
- UPSTREAM_OPTION_CATALOG,
188
- findOptionByFlag,
189
- listLongFlags,
190
- optionMetadata
191
- } from "yt-dlp-bridge";
131
+ import { UPSTREAM_OPTION_CATALOG, findOptionByFlag, listLongFlags, optionMetadata } from "yt-dlp-bridge";
192
132
 
193
133
  const format = findOptionByFlag("--format");
194
-
195
- console.log(UPSTREAM_OPTION_CATALOG.optionCount);
196
- console.log(listLongFlags().includes("--dump-json"));
134
+ console.log(UPSTREAM_OPTION_CATALOG.optionCount); // 323
135
+ console.log(listLongFlags().includes("--dump-json")); // true
197
136
  console.log(format ? optionMetadata(format) : undefined);
198
137
  ```
199
138
 
200
- ## API Surface
139
+ ## API
201
140
 
202
141
  | Area | Exports |
203
142
  | --- | --- |
204
143
  | Argv builders | `ytdlpCommand`, `buildMetadataArgs`, `buildSingleJsonArgs`, `buildListArgs`, `buildSimulationArgs`, `buildDownloadArgs` |
205
144
  | Planning | `planDownload`, `planPostprocess` |
206
- | Configuration and environment | `loadConfig`, `CONFIG`, `checkEnvironment` |
145
+ | Config and environment | `loadConfig`, `CONFIG`, `checkEnvironment` |
207
146
  | Filesystem policy | `resolveOutputPolicy`, `resolveManagedPath`, `ensureWithinRoot`, `isPathInside`, `isPathInsideWith`, `hasParentTraversal`, `ensureDirectory`, `readArchive` |
208
147
  | Option catalog | `UPSTREAM_OPTION_CATALOG`, `listLongFlags`, `findOptionByFlag`, `optionMetadata` |
209
148
  | Parsers | `parseJsonLines`, `sanitizeMetadataItem`, `sanitizeMetadataItems`, `paginate`, `parseFormats`, `parseSubtitles`, `parseThumbnails`, `parseProgress`, `parseFinalPaths` |
210
149
  | Process and errors | `runCommand`, `CommandExecutionError`, `toStructuredError` |
211
150
  | Redaction | `redactArgs`, `redactText`, `excerpt` |
212
- | Schemas and types | Zod input schemas and TypeScript interfaces exported from `src/index.ts` |
151
+ | Schemas and types | Zod input schemas and TypeScript interfaces |
213
152
 
214
153
  ## Configuration
215
154
 
216
- `loadConfig()` reads environment variables and applies conservative defaults.
155
+ `loadConfig(env?)` reads environment variables and applies conservative defaults. Pass a partial `ProcessEnv` object to override specific values.
217
156
 
218
157
  | Variable | Default | Purpose |
219
158
  | --- | --- | --- |
220
- | `YTDLP_MCP_YTDLP_PATH` or `YTDLP_PATH` | `yt-dlp` | Path or command name used for `yt-dlp`. |
159
+ | `YTDLP_MCP_YTDLP_PATH` or `YTDLP_PATH` | `yt-dlp` | Path or command name for `yt-dlp`. |
221
160
  | `YTDLP_MCP_FFMPEG_PATH` or `FFMPEG_PATH` | `ffmpeg` | Optional ffmpeg override for environment checks. |
222
161
  | `YTDLP_MCP_FFPROBE_PATH` or `FFPROBE_PATH` | `ffprobe` | Optional ffprobe override for environment checks. |
223
162
  | `YTDLP_MCP_OUTPUT_ROOT` | `~/Downloads/yt-dlp-mcp` | Managed output root. |
224
- | `YTDLP_MCP_TEMP_ROOT` | OS temp directory under `yt-dlp-mcp` | Managed temp root. |
225
- | `YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS` | `false` | Allows output and temp paths outside the configured roots. |
226
- | `YTDLP_MCP_ALLOW_CONFIG_FILES` | `false` | Allows user-provided cookies, netrc, and related config-file inputs unless they match server-level settings. |
163
+ | `YTDLP_MCP_TEMP_ROOT` | OS temp under `yt-dlp-mcp` | Managed temp root. |
164
+ | `YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS` | `false` | Allow output paths outside the configured roots. |
165
+ | `YTDLP_MCP_ALLOW_CONFIG_FILES` | `false` | Allow user-provided cookies, netrc, and config-file inputs. |
166
+ | `YTDLP_MCP_ALLOW_PLUGIN_DIRS` | `false` | Allow user-provided plugin directory paths. |
227
167
  | `YTDLP_MCP_COOKIES_FILE` | unset | Server-level cookies file. |
228
168
  | `YTDLP_MCP_COOKIES_FROM_BROWSER` | unset | Server-level browser cookie source for `--cookies-from-browser`. |
229
- | `YTDLP_MCP_ENABLE_EXPERT` | `false` | Enables higher-risk expert-mode integrations in callers that expose them. |
230
- | `YTDLP_MCP_TIMEOUT_MS` | `900000` | Default command timeout. |
231
- | `YTDLP_MCP_MAX_OUTPUT_BYTES` | `4194304` | Maximum retained stdout or stderr bytes. |
169
+ | `YTDLP_MCP_ENABLE_EXPERT` | `false` | Enable higher-risk expert-mode integrations. |
170
+ | `YTDLP_MCP_TIMEOUT_MS` | `900000` | Default command timeout (ms). |
171
+ | `YTDLP_MCP_MAX_OUTPUT_BYTES` | `4194304` | Maximum retained stdout/stderr bytes. |
232
172
  | `YTDLP_MCP_JS_RUNTIMES` | `deno,node,bun,quickjs` | JavaScript runtimes considered for extractor challenges. |
233
173
 
234
174
  ## Requirements
235
175
 
236
- - Node.js >= 22.13.
237
- - ESM import support.
238
- - `yt-dlp` installed when planning or running real yt-dlp workflows.
239
- - `ffmpeg` and `ffprobe` for audio extraction, audio/video merge, remuxing, recoding, segment editing, subtitle conversion, thumbnail conversion, and embedding workflows.
240
- - Python `yt_dlp` package, or `PYTHONPATH` pointed at a yt-dlp source checkout, when regenerating or verifying the option catalog.
176
+ - Node.js >= 22.13, ESM.
177
+ - `yt-dlp` installed when planning or running yt-dlp workflows.
178
+ - `ffmpeg` and `ffprobe` for audio extraction, merge, remux, recode, segment editing, subtitle/thumbnail conversion, and embedding workflows.
179
+ - Python `yt_dlp` package (or `PYTHONPATH` pointing at a yt-dlp checkout) when regenerating or verifying the option catalog.
241
180
 
242
181
  ## Development
243
182
 
183
+ ```bash
184
+ git clone https://github.com/antonio-orionus/yt-dlp-bridge.git
185
+ cd yt-dlp-bridge
186
+ pnpm install
187
+ ```
188
+
244
189
  | Command | Description |
245
190
  | --- | --- |
246
191
  | `pnpm run build` | Compile TypeScript and copy generated assets into `dist`. |
247
192
  | `pnpm test` | Run Vitest tests. |
248
- | `pnpm run typecheck` | Run TypeScript without emitting files. |
249
- | `pnpm run generate:options` | Regenerate the source-derived yt-dlp option catalog from Python `yt_dlp`. |
250
- | `pnpm run verify:options` | Verify that the generated option catalog matches Python `yt_dlp`. |
251
- | `pnpm pack --dry-run` | Preview the package contents before publishing. |
252
-
253
- ## Release
254
-
255
- GitHub Actions handles CI and npm publishing:
256
-
257
- - `.github/workflows/ci.yml` runs typecheck, tests, build, and package dry-run on pull requests and pushes to `main`.
258
- - `.github/workflows/release.yml` publishes to npm when a `vX.Y.Z` tag is pushed and the tag matches `package.json`.
259
- - Publishing uses npm trusted publishing with GitHub Actions OIDC and publishes an attested npm tarball with `npm publish ./npm-artifacts/*.tgz --access public`; no `NPM_TOKEN` secret is required when the trusted publisher is configured. npm automatically generates provenance for trusted publishes from GitHub Actions.
260
-
261
- The npm trusted publisher should point at:
262
-
263
- ```text
264
- repository: antonio-orionus/yt-dlp-bridge
265
- workflow file: release.yml
266
- environment: npm
267
- ```
268
-
269
- Release flow:
270
-
271
- ```bash
272
- pnpm version patch
273
- git push origin main --follow-tags
274
- ```
275
-
276
- ## Project Structure
277
-
278
- ```text
279
- yt-dlp-bridge/
280
- ├── .github/workflows/ # CI and npm publish automation
281
- ├── src/ # TypeScript source and generated option catalog
282
- ├── tests/ # Vitest coverage for argv, policy, parsers, planning, and errors
283
- ├── scripts/ # Option catalog generation and package asset scripts
284
- ├── dist/ # Built package output
285
- ├── package.json # Package metadata, exports, scripts, and npm keywords
286
- └── README.md # Package and repository documentation
287
- ```
193
+ | `pnpm run typecheck` | TypeScript check without emitting. |
194
+ | `pnpm run generate:options` | Regenerate the option catalog from Python `yt_dlp`. |
195
+ | `pnpm run verify:options` | Verify the catalog matches Python `yt_dlp`. |
196
+ | `pnpm pack --dry-run` | Preview package contents before publishing. |
288
197
 
289
198
  ## Troubleshooting
290
199
 
291
- ### `yt-dlp` is missing
292
-
293
- Install `yt-dlp` or set `YTDLP_MCP_YTDLP_PATH` to the executable path. `checkEnvironment()` reports the detected command, status, version, and notes.
294
-
295
- ### `ffmpeg` or `ffprobe` is missing
296
-
297
- Install the missing binary or set `YTDLP_MCP_FFMPEG_PATH` and `YTDLP_MCP_FFPROBE_PATH`. Planning still returns dependency information so callers can explain which workflow requires the missing tool.
298
-
299
- ### `auth.cookiesFile requires YTDLP_MCP_ALLOW_CONFIG_FILES=true`
300
-
301
- User-provided config-file paths are blocked by default. Prefer server-level `YTDLP_MCP_COOKIES_FILE` or enable `YTDLP_MCP_ALLOW_CONFIG_FILES=true` only when the caller has reviewed the trust boundary.
200
+ **`yt-dlp` is missing** — Install `yt-dlp` or set `YTDLP_MCP_YTDLP_PATH`. `checkEnvironment()` reports detected command, status, version, and notes.
302
201
 
303
- ### `outputTemplate must not contain parent-directory traversal`
202
+ **`ffmpeg`/`ffprobe` missing** — Install the binary or set `YTDLP_MCP_FFMPEG_PATH` / `YTDLP_MCP_FFPROBE_PATH`. Planning still returns dependency info so callers can surface which workflow requires the missing tool.
304
203
 
305
- Relative output templates cannot contain `..` path segments unless arbitrary output paths are explicitly allowed by policy.
204
+ **`auth.cookiesFile requires YTDLP_MCP_ALLOW_CONFIG_FILES=true`** — User-provided config-file paths are blocked by default. Prefer server-level `YTDLP_MCP_COOKIES_FILE` or enable `YTDLP_MCP_ALLOW_CONFIG_FILES=true` only after reviewing the trust boundary.
306
205
 
307
- ## Contributing
206
+ **`outputTemplate must not contain parent-directory traversal`** — Relative templates cannot contain `..` segments unless `YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS=true`.
308
207
 
309
- Use the development commands above before opening a pull request. Bugs and feature requests can be reported through [GitHub Issues](https://github.com/antonio-orionus/yt-dlp-bridge/issues).
208
+ Bugs and feature requests: [GitHub Issues](https://github.com/antonio-orionus/yt-dlp-bridge/issues).
310
209
 
311
210
  ## License
312
211
 
313
- [MIT](LICENSE)
212
+ [MIT](LICENSE) © 2026 Antonio Orionus
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "yt-dlp-bridge",
3
- "version": "0.1.5",
4
- "description": "TypeScript toolkit for safe yt-dlp command planning, argv generation, execution, parsing, and structured errors.",
3
+ "version": "0.1.6",
4
+ "description": "TypeScript library for safe, no-shell yt-dlp integration: command planning, argv generation, process execution, output parsing, and structured errors.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "author": "Antonio Orionus",
@@ -39,22 +39,22 @@
39
39
  },
40
40
  "keywords": [
41
41
  "yt-dlp",
42
- "yt-dlp-wrapper",
43
42
  "yt-dlp-node",
44
43
  "youtube-dl",
45
44
  "media-downloader",
46
45
  "video-downloader",
47
- "download-manager",
48
46
  "ffmpeg",
49
47
  "metadata-extraction",
50
48
  "command-builder",
51
49
  "argv",
50
+ "no-shell",
51
+ "subprocess",
52
+ "redaction",
53
+ "structured-errors",
52
54
  "typescript",
53
55
  "esm",
54
56
  "zod",
55
- "mcp",
56
- "planner",
57
- "wrapper"
57
+ "mcp"
58
58
  ],
59
59
  "dependencies": {
60
60
  "ytdlp-errors": "^1.1.0",