yt-dlp downloads (ytdlp)

Requires: FILE_ACCESS, NETWORK_REQUEST

Downloads media from supported sites using the bundled yt-dlp binary in the main process. Addons never spawn yt-dlp directly.

Setup

1. Add "FILE_ACCESS" and "NETWORK_REQUEST" to permissions in manifest.json.
2. Choose an output folder:
   • User folder: request manage access before downloading (files.requestAccess(folder, 'manage')).
   • Addon temp folder: write under ADDON_TMP_DIR — no consent dialog is required.
3. Subscribe to progress, then call ytdlp.downloadFile.

const folder = 'C:\\Videos\\clips';
const access = await files.requestAccess(folder, 'manage');
if (!access.success) {
  console.warn(access.message);
  return;
}

{
  "id": "my-addon",
  "permissions": ["FILE_ACCESS", "NETWORK_REQUEST"]
}

How it works

• Downloads run in the main process via the bundled yt-dlp binary (yt-dlp_linux, yt-dlp_macos, yt-dlp.exe).
• The output path is passed to yt-dlp -o. You may use yt-dlp output template variables in the filename (see below).
• Literal (non-template) parts of the path are sanitized to remove invalid filename characters. Substituted values (for example %(title)s) are kept as-is, including Cyrillic characters.
• The parent directory of the output path must be covered by a user-approved manage file-access grant (files.requestAccess(folder, 'manage')), or lie under ADDON_TMP_DIR.
• Optional conversion flags map to yt-dlp: format → -f, extractAudio → -x, audioFormat → --audio-format, mergeOutputFormat → --merge-output-format.
• Progress is pushed to the addon worker as ytdlp:download-progress events while the download runs.
• Up to 10 parallel HLS/DASH fragments can be requested with concurrentFragments (maps to --concurrent-fragments).

ytdlp.downloadFile(url, outputPath, options?)

Returns:

{
  success: boolean,
  downloadId?: string,
  error?: YtDlpAddonErrorCode,
  message?: string,
}

Progress (ytdlp:download-progress)

Subscribe before calling downloadFile:

const downloadId = random.id();

events.On('ytdlp:download-progress', ({ downloadId: id, progress }) => {
  if (id !== downloadId) return;

  console.log(progress.stage, progress.percent, progress.speed, progress.eta);
  // progress.downloadedBytes, progress.totalBytes
});

progress.stage is 'downloading' during the transfer, 'done' on success, and 'cancelled' when ytdlp.cancelDownload stops the process.

ytdlp.cancelDownload(downloadId)

Stops an active download started with the same downloadId. The original downloadFile promise resolves with success: false and error: 'cancelled'.

Returns:

{
  success: boolean,
  downloadId?: string,
  error?: 'no_permission' | 'not_found' | 'invalid_download_id',
  message?: string,
}

Cancel example

const downloadId = random.id();
const downloadPromise = ytdlp.downloadFile(url, outputPath, { downloadId });

cancelButton.onClick(async () => {
  const cancelled = await ytdlp.cancelDownload(downloadId);
  if (!cancelled.success) {
    console.warn(cancelled.error, cancelled.message);
  }
});

const result = await downloadPromise;
if (result.error === 'cancelled') {
  console.log('Download stopped by user');
}

Example

const outputDir = 'C:\\Videos\\clips';
await files.requestAccess(outputDir, 'manage');

const downloadId = random.id();
events.On('ytdlp:download-progress', ({ downloadId: id, progress }) => {
  if (id !== downloadId) return;
  status.Update({
    current: 'online',
    message: { en: `Downloading ${progress.percent.toFixed(1)}%` },
  });
});

const result = await ytdlp.downloadFile(
  'https://www.twitch.tv/videos/1234567890',
  `${outputDir}\\%(uploader)s - %(title)s.%(ext)s`,
  {
    downloadId,
    concurrentFragments: 4,
    format: 'bv*[height<=720]+ba/b[height<=720]',
    mergeOutputFormat: 'mp4',
  }
);

if (!result.success) {
  console.warn(result.error, result.message);
}

Audio-only into ADDON_TMP_DIR

const sep = ADDON_TMP_DIR.includes('\\') ? '\\' : '/';
const outputPath = `${ADDON_TMP_DIR}${sep}track.%(ext)s`;

const result = await ytdlp.downloadFile(url, outputPath, {
  format: 'ba/bestaudio',
  extractAudio: true,
  audioFormat: 'm4a',
});

Output template variables

You can embed yt-dlp fields in outputPath. Common variables:

Identification

Format

Author / channel

Date and time

Duration

Statistics

Metadata

Playlists

Subtitles

Site / extractor

Twitch-specific

Full list: yt-dlp output template

Error codes

When success is false, error is one of:

cancelDownload errors:

message contains a human-readable detail string when available (often yt-dlp stderr).

Related

• File access — files.requestAccess, grants, revoke
• Permissions
• API overview