Загрузки через 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: { ru: `Загрузка ${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