@x12i/youtube-video-uploader-cli 1.3.0 → 1.6.1

package/src/media/compose.js

@@ -3,6 +3,7 @@ import ffmpegStatic from 'ffmpeg-static';
 import ffprobeStatic from 'ffprobe-static';
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 
 // Configure ffmpeg and ffprobe paths if available
 if (ffmpegStatic && fs.existsSync(ffmpegStatic)) {
@@ -12,6 +13,47 @@ if (ffprobeStatic?.path && fs.existsSync(ffprobeStatic.path)) {
   ffmpeg.setFfprobePath(ffprobeStatic.path);
 }
 
+const ASS_FILTER_UNSAFE = /['\[\]:;\\,]/;
+
+/**
+ * Return a safe path to pass to ffmpeg's `ass=` filter.
+ *
+ * @param {string} assPath
+ * @returns {{ filterPath: string | null, cleanupPath?: string }}
+ */
+export function resolveAssFilterPath(assPath) {
+  if (!assPath || !fs.existsSync(assPath)) {
+    return { filterPath: null };
+  }
+  if (!ASS_FILTER_UNSAFE.test(assPath)) {
+    return { filterPath: assPath };
+  }
+  const cleanupPath = path.join(
+    os.tmpdir(),
+    `compose-ass-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.ass`
+  );
+  try {
+    fs.copyFileSync(assPath, cleanupPath);
+    return { filterPath: cleanupPath, cleanupPath };
+  } catch {
+    return { filterPath: assPath };
+  }
+}
+
+/**
+ * Quote and escape special characters in path for ffmpeg filter syntax.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function escapeForFfmpeg(filePath) {
+  const escaped = String(filePath)
+    .replaceAll('\\', '\\\\')
+    .replaceAll(':', '\\:')
+    .replaceAll("'", "\\'");
+  return `'${escaped}'`;
+}
+
 /**
  * Get the duration of an audio or video file in seconds using ffprobe.
  *
@@ -72,6 +114,7 @@ export async function composeVideo(options) {
     targetHeight = 1080,
     fps = 30,
     dryRun = false,
+    assPath = null,
     onProgress,
   } = options;
 
@@ -98,12 +141,31 @@ export async function composeVideo(options) {
   }
 
   const isImage = bgDuration === 0 || mode === 'ken-burns';
-  const scaleCropFilter = `scale=${targetWidth}:${targetHeight}:force_original_aspect_ratio=increase,crop=${targetWidth}:${targetHeight},format=yuv420p`;
+  const baseScaleFilter = `scale=${targetWidth}:${targetHeight}:force_original_aspect_ratio=increase,crop=${targetWidth}:${targetHeight},format=yuv420p`;
+
+  let assCleanupPath = null;
+  let scaleCropFilter = baseScaleFilter;
+  if (assPath && fs.existsSync(assPath)) {
+    const resolved = resolveAssFilterPath(assPath);
+    if (resolved.filterPath) {
+      assCleanupPath = resolved.cleanupPath || null;
+      scaleCropFilter = `${baseScaleFilter},ass=${escapeForFfmpeg(resolved.filterPath)}`;
+    }
+  }
+
+  const cleanup = () => {
+    if (assCleanupPath && fs.existsSync(assCleanupPath)) {
+      try { fs.unlinkSync(assCleanupPath); } catch {}
+      assCleanupPath = null;
+    }
+  };
 
   if (dryRun) {
+    cleanup();
+    const subsNote = assPath ? ` + subtitles (${path.basename(assPath)})` : '';
     const planDescription = isImage
-      ? `Image (${backgroundPath}) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s) -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`
-      : `Video (${backgroundPath}, ${bgDuration.toFixed(1)}s) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s) -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`;
+      ? `Image (${backgroundPath}) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s)${subsNote} -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`
+      : `Video (${backgroundPath}, ${bgDuration.toFixed(1)}s) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s)${subsNote} -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`;
 
     return {
       outputPath,
@@ -116,15 +178,22 @@ export async function composeVideo(options) {
   return new Promise((resolve, reject) => {
     const command = ffmpeg();
 
+    const audioOpts = [
+      '-c:a', 'aac',
+      '-b:a', '320k',
+      '-ar', '48000',
+    ];
+
     if (isImage) {
       if (mode === 'ken-burns') {
         const totalFrames = Math.max(30, Math.ceil(audioDuration * fps));
+        const kenBurnsFilter = `scale=8000:-1,zoompan=z='min(zoom+0.0008,1.25)':d=${totalFrames}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=${targetWidth}x${targetHeight}:fps=${fps},${scaleCropFilter}`;
         command
           .input(backgroundPath)
           .inputOptions(['-loop', '1'])
           .input(audioPath)
           .complexFilter([
-            `scale=8000:-1,zoompan=z='min(zoom+0.0008,1.25)':d=${totalFrames}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=${targetWidth}x${targetHeight}:fps=${fps},${scaleCropFilter}[v]`,
+            `${kenBurnsFilter}[v]`,
           ])
           .outputOptions([
             '-map', '[v]',
@@ -132,8 +201,7 @@ export async function composeVideo(options) {
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             '-pix_fmt', 'yuv420p',
@@ -147,11 +215,12 @@ export async function composeVideo(options) {
           .input(audioPath)
           .videoFilters([scaleCropFilter])
           .outputOptions([
+            '-map', '0:v',
+            '-map', '1:a',
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             `-r`, `${fps}`,
@@ -169,11 +238,12 @@ export async function composeVideo(options) {
           .input(audioPath)
           .videoFilters([scaleCropFilter])
           .outputOptions([
+            '-map', '0:v',
+            '-map', '1:a',
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             `-r`, `${fps}`,
@@ -187,11 +257,12 @@ export async function composeVideo(options) {
           .input(audioPath)
           .videoFilters([scaleCropFilter])
           .outputOptions([
+            '-map', '0:v',
+            '-map', '1:a',
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             `-r`, `${fps}`,
@@ -208,12 +279,14 @@ export async function composeVideo(options) {
     command
       .output(outputPath)
       .on('end', () => {
+        cleanup();
         resolve({
           outputPath,
           duration: audioDuration,
         });
       })
       .on('error', (err) => {
+        cleanup();
         // Clean up partial output if any
         if (fs.existsSync(outputPath)) {
           try {

package/src/playlist/detect-outdated.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Find local MP4 files that changed after their last YouTube upload timestamp.
+ *
+ * @param {string} targetDir
+ * @param {import('../state.js').UploadState} state
+ * @param {object} [options]
+ * @param {number} [options.toleranceMs=1000] - Ignore sub-second clock skew
+ * @param {string[]} [options.onlyFilenames] - Restrict to these basenames
+ * @returns {Array<{ filename: string, filePath: string, videoId: string, uploadedAt: string, modifiedAt: string }>}
+ */
+export function detectOutdatedUploads(targetDir, state, options = {}) {
+  const toleranceMs = options.toleranceMs ?? 1000;
+  const only = options.onlyFilenames
+    ? new Set(options.onlyFilenames.map((f) => path.basename(f)))
+    : null;
+
+  const outdated = [];
+  const uploads = state.data.uploads || {};
+
+  for (const [filename, record] of Object.entries(uploads)) {
+    if (only && !only.has(filename)) continue;
+    if (!record?.videoId || !record?.uploadedAt) continue;
+
+    const filePath = path.join(targetDir, filename);
+    if (!fs.existsSync(filePath)) continue;
+
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size === 0) continue;
+
+    const modifiedMs = stat.mtimeMs;
+    const uploadedMs = new Date(record.uploadedAt).getTime();
+    if (Number.isNaN(uploadedMs)) continue;
+
+    if (modifiedMs > uploadedMs + toleranceMs) {
+      outdated.push({
+        filename,
+        filePath,
+        videoId: record.videoId,
+        uploadedAt: record.uploadedAt,
+        modifiedAt: new Date(modifiedMs).toISOString(),
+      });
+    }
+  }
+
+  outdated.sort((a, b) => a.filename.localeCompare(b.filename));
+  return outdated;
+}

package/src/playlist/order.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadMetadata } from '../metadata.js';
+
+/**
+ * Resolve desired playlist video IDs from upload histories + metadata song order.
+ *
+ * @param {object} options
+ * @param {string} options.albumDir
+ * @param {import('../state.js').UploadState} options.albumState
+ * @param {string} [options.overviewHistoryPath]
+ * @param {string[]} [options.overviewKeys]
+ * @param {string[]} [options.songKeys]
+ * @returns {string[]}
+ */
+export function resolveDesiredPlaylistOrder(options = {}) {
+  const {
+    albumDir,
+    albumState,
+    overviewHistoryPath,
+    overviewKeys = [],
+    songKeys,
+  } = options;
+
+  const ids = [];
+
+  if (overviewHistoryPath && overviewKeys.length > 0) {
+    const abs = path.resolve(overviewHistoryPath);
+    if (!fs.existsSync(abs)) {
+      throw new Error(`Overview upload history not found: ${abs}`);
+    }
+    const overviewHistory = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+    for (const key of overviewKeys) {
+      const rec = overviewHistory.uploads?.[key];
+      if (!rec?.videoId) {
+        throw new Error(`Overview upload history missing videoId for ${key}`);
+      }
+      ids.push(rec.videoId);
+    }
+  }
+
+  let orderedSongs = songKeys;
+  if (!orderedSongs || orderedSongs.length === 0) {
+    const metadata = loadMetadata(albumDir);
+    orderedSongs = metadata.videos.map((v) => v.filename);
+  }
+
+  for (const filename of orderedSongs) {
+    const rec = albumState.getUpload(filename);
+    if (!rec?.videoId) {
+      throw new Error(`Album upload history missing videoId for ${filename}`);
+    }
+    ids.push(rec.videoId);
+  }
+
+  return ids;
+}

package/src/playlist/reorder.js

@@ -0,0 +1,90 @@
+/**
+ * List all playlist items with snippet data.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} playlistId
+ * @returns {Promise<Array<{ id: string, videoId: string, position: number, title: string }>>}
+ */
+export async function listPlaylistItems(youtube, playlistId) {
+  const items = [];
+  let pageToken;
+  do {
+    const { data } = await youtube.playlistItems.list({
+      part: ['snippet'],
+      playlistId,
+      maxResults: 50,
+      pageToken,
+    });
+    for (const item of data.items || []) {
+      items.push({
+        id: item.id,
+        videoId: item.snippet?.resourceId?.videoId,
+        position: item.snippet?.position ?? 0,
+        title: item.snippet?.title || '',
+      });
+    }
+    pageToken = data.nextPageToken;
+  } while (pageToken);
+
+  items.sort((a, b) => a.position - b.position);
+  return items;
+}
+
+/**
+ * Reorder a playlist to match an explicit video ID sequence.
+ * Updates positions from end to start to avoid index drift.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} playlistId
+ * @param {string[]} desiredVideoIds
+ * @returns {Promise<{ changed: number, finalOrder: string[] }>}
+ */
+export async function reorderPlaylist(youtube, playlistId, desiredVideoIds) {
+  if (!desiredVideoIds.length) {
+    throw new Error('desiredVideoIds must not be empty');
+  }
+
+  const items = await listPlaylistItems(youtube, playlistId);
+  const byVideo = new Map(items.map((item) => [item.videoId, item]));
+
+  for (const videoId of desiredVideoIds) {
+    if (!byVideo.has(videoId)) {
+      throw new Error(`Video ${videoId} is not in playlist ${playlistId}`);
+    }
+  }
+
+  let changed = 0;
+  for (let pos = desiredVideoIds.length - 1; pos >= 0; pos -= 1) {
+    const videoId = desiredVideoIds[pos];
+    const item = byVideo.get(videoId);
+    if (item.position === pos) continue;
+
+    await youtube.playlistItems.update({
+      part: ['snippet'],
+      requestBody: {
+        id: item.id,
+        snippet: {
+          playlistId,
+          resourceId: { kind: 'youtube#video', videoId },
+          position: pos,
+        },
+      },
+    });
+    item.position = pos;
+    changed += 1;
+  }
+
+  return { changed, finalOrder: desiredVideoIds };
+}
+
+/**
+ * Compare current playlist order to desired video IDs.
+ *
+ * @param {string[]} currentVideoIds
+ * @param {string[]} desiredVideoIds
+ * @returns {boolean}
+ */
+export function playlistOrderMatches(currentVideoIds, desiredVideoIds) {
+  if (currentVideoIds.length !== desiredVideoIds.length) return false;
+  return currentVideoIds.every((id, i) => id === desiredVideoIds[i]);
+}

package/src/playlist/sync.js

@@ -0,0 +1,192 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { UploadState } from '../state.js';
+import { swapSong } from '../swap/swapSong.js';
+import { detectOutdatedUploads } from './detect-outdated.js';
+import { resolveDesiredPlaylistOrder } from './order.js';
+import {
+  listPlaylistItems,
+  playlistOrderMatches,
+  reorderPlaylist,
+} from './reorder.js';
+
+/**
+ * Sync a YouTube playlist with local files: push outdated uploads via swap,
+ * then realign playlist order. Keeps videos private by default.
+ *
+ * @param {object} options
+ * @param {import('googleapis').youtube_v3.Youtube} options.youtube
+ * @param {string} options.albumDir
+ * @param {string} options.playlistId
+ * @param {string} [options.overviewHistoryPath]
+ * @param {string[]} [options.overviewKeys]
+ * @param {string[]} [options.songKeys]
+ * @param {string[]} [options.onlyFilenames]
+ * @param {'preserve' | 'private' | 'public'} [options.privacyMode='private']
+ * @param {boolean} [options.dryRun=false]
+ * @param {boolean} [options.skipReorder=false]
+ * @param {boolean} [options.freshSwap=false]
+ * @param {string} [options.stateFile]
+ * @param {(event: object) => void} [options.onEvent]
+ * @returns {Promise<object>}
+ */
+export async function syncPlaylist(options = {}) {
+  const {
+    youtube,
+    albumDir,
+    playlistId,
+    overviewHistoryPath,
+    overviewKeys = [],
+    songKeys,
+    onlyFilenames,
+    privacyMode = 'private',
+    dryRun = false,
+    skipReorder = false,
+    freshSwap = false,
+    stateFile,
+    onEvent = () => {},
+  } = options;
+
+  if (!albumDir || !playlistId) {
+    throw new Error('syncPlaylist requires albumDir and playlistId');
+  }
+
+  const resolvedAlbumDir = path.resolve(albumDir);
+  const albumState = new UploadState(resolvedAlbumDir, stateFile);
+
+  const outdated = detectOutdatedUploads(resolvedAlbumDir, albumState, { onlyFilenames });
+  const desiredOrder = resolveDesiredPlaylistOrder({
+    albumDir: resolvedAlbumDir,
+    albumState,
+    overviewHistoryPath,
+    overviewKeys,
+    songKeys,
+  });
+
+  let currentOrder = [];
+  if (!dryRun && youtube) {
+    const currentItems = await listPlaylistItems(youtube, playlistId);
+    currentOrder = currentItems.map((item) => item.videoId);
+  }
+
+  const plan = {
+    playlistId,
+    albumDir: resolvedAlbumDir,
+    privacyMode,
+    outdated,
+    desiredOrder,
+    currentOrder,
+    orderAligned: currentOrder.length
+      ? playlistOrderMatches(currentOrder, desiredOrder)
+      : null,
+    swaps: outdated.map((item) => ({
+      filename: item.filename,
+      oldVideoId: item.videoId,
+      modifiedAt: item.modifiedAt,
+      uploadedAt: item.uploadedAt,
+    })),
+  };
+
+  onEvent({ type: 'sync_plan', plan });
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      ...plan,
+      pushed: [],
+      reordered: false,
+    };
+  }
+
+  if (!youtube) {
+    throw new Error('syncPlaylist requires an authorized youtube client when dryRun is false');
+  }
+
+  const pushed = [];
+  const failed = [];
+
+  for (const item of outdated) {
+    onEvent({ type: 'sync_push_start', filename: item.filename, oldVideoId: item.videoId });
+    try {
+      const { record } = await swapSong({
+        youtube,
+        songKey: item.filename,
+        newVideoPath: item.filePath,
+        playlistId,
+        oldVideoId: item.videoId,
+        stateDir: resolvedAlbumDir,
+        fresh: freshSwap,
+        privacyMode,
+        onEvent: (event) => onEvent({ ...event, filename: item.filename }),
+      });
+
+      albumState.data.uploads[item.filename] = {
+        ...albumState.data.uploads[item.filename],
+        videoId: record.newVideoId,
+        uploadedAt: new Date().toISOString(),
+        playlistId,
+        previousVideoId: item.videoId,
+      };
+      albumState.save();
+
+      pushed.push({
+        filename: item.filename,
+        oldVideoId: item.videoId,
+        newVideoId: record.newVideoId,
+        url: `https://youtu.be/${record.newVideoId}`,
+      });
+      onEvent({ type: 'sync_push_success', filename: item.filename, record });
+    } catch (err) {
+      failed.push({ filename: item.filename, error: err });
+      onEvent({ type: 'sync_push_error', filename: item.filename, error: err });
+      throw err;
+    }
+  }
+
+  const refreshedDesiredOrder = resolveDesiredPlaylistOrder({
+    albumDir: resolvedAlbumDir,
+    albumState,
+    overviewHistoryPath,
+    overviewKeys,
+    songKeys,
+  });
+
+  let reorderResult = { changed: 0, finalOrder: refreshedDesiredOrder };
+  if (!skipReorder) {
+    const latestItems = await listPlaylistItems(youtube, playlistId);
+    const latestOrder = latestItems.map((item) => item.videoId);
+    if (!playlistOrderMatches(latestOrder, refreshedDesiredOrder)) {
+      onEvent({ type: 'sync_reorder_start', desiredOrder: refreshedDesiredOrder });
+      reorderResult = await reorderPlaylist(youtube, playlistId, refreshedDesiredOrder);
+      onEvent({ type: 'sync_reorder_success', ...reorderResult });
+    }
+  }
+
+  if (overviewHistoryPath && overviewKeys.length > 0) {
+    const absOverviewHistory = path.resolve(overviewHistoryPath);
+    if (fs.existsSync(absOverviewHistory)) {
+      const overviewHistory = JSON.parse(fs.readFileSync(absOverviewHistory, 'utf-8'));
+      overviewHistory.playlistId = playlistId;
+      overviewHistory.playlistOrder = refreshedDesiredOrder;
+      overviewHistory.updatedAt = new Date().toISOString();
+      fs.writeFileSync(absOverviewHistory, JSON.stringify(overviewHistory, null, 2) + '\n');
+    }
+  }
+
+  albumState.data.playlistId = playlistId;
+  albumState.data.playlistOrder = refreshedDesiredOrder;
+  albumState.data.updatedAt = new Date().toISOString();
+  albumState.save();
+
+  return {
+    dryRun: false,
+    playlistId,
+    pushed,
+    failed,
+    outdated,
+    desiredOrder: refreshedDesiredOrder,
+    reordered: reorderResult.changed > 0,
+    reorderChanges: reorderResult.changed,
+    orderAligned: true,
+  };
+}

package/src/providers/watermark/index.js

@@ -0,0 +1,113 @@
+/**
+ * Watermark-remover provider registry.
+ *
+ * Only register tools with permissive open-source licenses:
+ * MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, or ISC.
+ *
+ * To add another MIT/Apache/BSD/ISC npm CLI later:
+ * 1. Create `src/providers/watermark/<id>.js` with a `run*Remove` entry point
+ * 2. Register it in PROVIDERS below
+ * 3. No pipeline changes required
+ */
+
+import {
+  PILIO_PROVIDER_ID,
+  PILIO_LICENSE,
+  runPilioRemove,
+  formatPilioCommand,
+  buildPilioArgs,
+  resolvePilioBin,
+} from './pilio.js';
+
+/** @typedef {'MIT' | 'Apache-2.0' | 'BSD-2-Clause' | 'BSD-3-Clause' | 'ISC'} PermissiveLicense */
+
+/**
+ * @typedef {object} WatermarkProvider
+ * @property {string} id
+ * @property {PermissiveLicense} license
+ * @property {string} packageName
+ * @property {(options: object) => Promise<{ outputPath?: string, outDir?: string, dryRun?: boolean, command: string, exitCode?: number, stdout?: string }>} remove
+ */
+
+/** @type {Record<string, WatermarkProvider>} */
+const PROVIDERS = {
+  [PILIO_PROVIDER_ID]: {
+    id: PILIO_PROVIDER_ID,
+    license: PILIO_LICENSE,
+    packageName: '@pilio/gemini-watermark-remover',
+    remove: runPilioRemove,
+  },
+};
+
+export const DEFAULT_WATERMARK_PROVIDER = PILIO_PROVIDER_ID;
+
+export const PERMISSIVE_LICENSES = Object.freeze([
+  'MIT',
+  'Apache-2.0',
+  'BSD-2-Clause',
+  'BSD-3-Clause',
+  'ISC',
+]);
+
+/**
+ * List registered watermark providers.
+ * @returns {Array<{ id: string, license: string, packageName: string }>}
+ */
+export function listWatermarkProviders() {
+  return Object.values(PROVIDERS).map(({ id, license, packageName }) => ({
+    id,
+    license,
+    packageName,
+  }));
+}
+
+/**
+ * Resolve a watermark provider by id (default: pilio).
+ * @param {string} [providerId]
+ * @returns {WatermarkProvider}
+ */
+export function getWatermarkProvider(providerId = DEFAULT_WATERMARK_PROVIDER) {
+  const id = String(providerId || DEFAULT_WATERMARK_PROVIDER).trim().toLowerCase();
+  const provider = PROVIDERS[id];
+  if (!provider) {
+    const known = Object.keys(PROVIDERS).join(', ');
+    throw new Error(
+      `Unknown watermark provider "${providerId}". Known providers: ${known}. ` +
+      `Only permissive-license tools (${PERMISSIVE_LICENSES.join(', ')}) may be registered.`
+    );
+  }
+  if (!PERMISSIVE_LICENSES.includes(provider.license)) {
+    throw new Error(
+      `Watermark provider "${provider.id}" has disallowed license "${provider.license}". ` +
+      `Allowed: ${PERMISSIVE_LICENSES.join(', ')}.`
+    );
+  }
+  return provider;
+}
+
+/**
+ * Remove a Gemini/Veo visible watermark via the selected provider.
+ *
+ * @param {object} options
+ * @param {string} options.inputPath
+ * @param {string} [options.outputPath]
+ * @param {string} [options.outDir]
+ * @param {string} [options.provider]
+ * @param {boolean} [options.overwrite]
+ * @param {boolean} [options.json]
+ * @param {number} [options.videoBitrateMbps]
+ * @param {boolean} [options.dryRun]
+ * @param {(chunk: string) => void} [options.onStderr]
+ */
+export async function removeWatermarkWithProvider(options = {}) {
+  const provider = getWatermarkProvider(options.provider);
+  return provider.remove(options);
+}
+
+export {
+  runPilioRemove,
+  formatPilioCommand,
+  buildPilioArgs,
+  resolvePilioBin,
+  PILIO_PROVIDER_ID,
+};