Завантаження через yt-dlp (ytdlp)

Потрібно: FILE_ACCESS, NETWORK_REQUEST

Завантаження медіа з підтримуваних сайтів через вбудований бінарник yt-dlp у головному процесі. Аддон не запускає yt-dlp напряму.

Налаштування

1. Додайте "FILE_ACCESS" і "NETWORK_REQUEST" до permissions у manifest.json.
2. Оберіть папку призначення:
   • Папка користувача: запросіть доступ manage (files.requestAccess(folder, 'manage')).
   • Тимчасова папка аддона: пишіть у ADDON_TMP_DIR — діалог згоди не потрібен.
3. Підпишіться на прогрес і викличте 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"]
}

Як це працює

• Завантаження виконується в головному процесі через вбудований yt-dlp (yt-dlp_linux, yt-dlp_macos, yt-dlp.exe).
• Шлях збереження передається в yt-dlp -o. У імені файлу можна використовувати змінні шаблону yt-dlp (див. нижче).
• Літеральні (не шаблонні) частини шляху очищуються від недопустимих символів. Підставлені значення (наприклад %(title)s) зберігаються як є, включно з кирилицею.
• Батьківська папка вихідного шляху має бути покрита схваленим користувачем грантом manage (files.requestAccess(folder, 'manage')) або лежати всередині ADDON_TMP_DIR.
• Опції конвертації: format → -f, extractAudio → -x, audioFormat → --audio-format, mergeOutputFormat → --merge-output-format.
• Прогрес надходить у воркер аддона подією ytdlp:download-progress.
• Паралельні HLS/DASH-фрагменти (concurrentFragments) — від 1 до 10 (--concurrent-fragments).

ytdlp.downloadFile(url, outputPath, options?)

Повертає:

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

Прогрес (ytdlp:download-progress)

Підпишіться до виклику 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 — 'downloading' під час завантаження, 'done' при успіху та 'cancelled' при зупинці через ytdlp.cancelDownload.

ytdlp.cancelDownload(downloadId)

Перериває активне завантаження з тим самим downloadId. Проміс downloadFile завершиться з success: false і error: 'cancelled'.

Повертає:

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

Приклад скасування

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('Завантаження зупинено користувачем');
}

Приклад

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: { uk: `Завантаження ${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 }
);

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

Змінні шаблону виводу

У outputPath можна використовувати поля yt-dlp. Основні змінні:

Ідентифікація

Формат

Автор / канал

Дата й час

Тривалість

Статистика

Метадані

Плейлисти

Субтитри

Сайт / екстрактор

Twitch

Повний список: шаблон виводу yt-dlp

Коди помилок

При success: false поле error:

Помилки cancelDownload:

message — зрозумілий опис (часто stderr yt-dlp).

Див. також

• Доступ до файлів
• Дозволи
• Огляд API