ytdlp-react-native 1.0.0 → 1.1.0-beta.0

package/src/__tests__/mappers.test.ts

@@ -0,0 +1,167 @@
+import { mapDownloadProgress, mapFormat, mapVideoInfo } from '../mappers';
+
+describe('mapVideoInfo', () => {
+  it('maps known fields and ignores unknown ones', () => {
+    const info = mapVideoInfo({
+      id: 'abc',
+      title: 'Hello',
+      duration: 12.5,
+      duration_string: '00:12',
+      view_count: 100,
+      is_live: true,
+      live_status: 'is_live',
+      extractor: 'youtube',
+      thumbnail: 'https://example.com/t.jpg',
+      formats: [],
+    });
+
+    expect(info.id).toBe('abc');
+    expect(info.title).toBe('Hello');
+    expect(info.duration).toBe(12.5);
+    expect(info.durationString).toBe('00:12');
+    expect(info.viewCount).toBe(100);
+    expect(info.isLive).toBe(true);
+    expect(info.wasLive).toBe(false);
+    expect(info.extractor).toBe('youtube');
+    expect(info.thumbnail).toBe('https://example.com/t.jpg');
+    expect(info.formats).toEqual([]);
+  });
+
+  it('treats missing fields as undefined', () => {
+    const info = mapVideoInfo({});
+    expect(info.title).toBeUndefined();
+    expect(info.duration).toBeUndefined();
+    expect(info.likeCount).toBeUndefined();
+    expect(info.formats).toEqual([]);
+  });
+
+  it('maps non-live statuses as not live', () => {
+    expect(mapVideoInfo({ live_status: 'was_live' }).wasLive).toBe(true);
+    expect(mapVideoInfo({ live_status: 'not_live' }).isLive).toBe(false);
+  });
+
+  it('normalizes thumbnails and falls back to the single thumbnail', () => {
+    const info = mapVideoInfo({
+      thumbnails: [
+        { url: 'https://example.com/a.jpg', width: 120, height: 90 },
+        { url: 'https://example.com/b.jpg' },
+      ],
+    });
+    expect(info.thumbnails).toHaveLength(2);
+    expect(info.thumbnails[0]).toEqual({
+      url: 'https://example.com/a.jpg',
+      width: 120,
+      height: 90,
+      resolution: undefined,
+      id: undefined,
+    });
+  });
+
+  it('skips thumbnails without a url and creates one from the single thumbnail', () => {
+    const info = mapVideoInfo({
+      thumbnails: [{ width: 10 }],
+      thumbnail: 'https://example.com/fallback.jpg',
+    });
+    expect(info.thumbnails).toHaveLength(1);
+    expect(info.thumbnails[0].url).toBe('https://example.com/fallback.jpg');
+  });
+
+  it('converts numeric strings to numbers', () => {
+    const info = mapVideoInfo({ duration: '42', view_count: '7' });
+    expect(info.duration).toBe(42);
+    expect(info.viewCount).toBe(7);
+  });
+});
+
+describe('mapFormat', () => {
+  it('maps a combined stream with video and audio', () => {
+    const format = mapFormat({
+      format_id: '18',
+      url: 'https://example.com/v.mp4',
+      ext: 'mp4',
+      width: 640,
+      height: 360,
+      vcodec: 'avc1',
+      acodec: 'mp4a',
+      filesize: 1000,
+    });
+
+    expect(format.id).toBe('18');
+    expect(format.url).toBe('https://example.com/v.mp4');
+    expect(format.width).toBe(640);
+    expect(format.hasVideo).toBe(true);
+    expect(format.hasAudio).toBe(true);
+    expect(format.audioOnly).toBe(false);
+    expect(format.videoOnly).toBe(false);
+  });
+
+  it('detects audio-only and video-only streams', () => {
+    const audio = mapFormat({ format_id: '140', vcodec: 'none', acodec: 'mp4a' });
+    expect(audio.hasAudio).toBe(true);
+    expect(audio.hasVideo).toBe(false);
+    expect(audio.audioOnly).toBe(true);
+
+    const video = mapFormat({ format_id: '137', vcodec: 'avc1', acodec: 'none' });
+    expect(video.hasVideo).toBe(true);
+    expect(video.hasAudio).toBe(false);
+    expect(video.videoOnly).toBe(true);
+  });
+
+  it('falls back to a blank string id rather than leaking garbage', () => {
+    expect(mapFormat({}).id).toBe('');
+    expect(mapFormat({}).hasVideo).toBe(false);
+  });
+
+  it('maps format id from either key', () => {
+    expect(mapFormat({ id: 'x' }).id).toBe('x');
+    expect(mapFormat({ format_id: 'y' }).id).toBe('y');
+  });
+
+  it('treats non-finite numbers as undefined', () => {
+    const format = mapFormat({ width: NaN, fps: 'NaN', abr: Infinity });
+    expect(format.width).toBeUndefined();
+    expect(format.fps).toBeUndefined();
+    expect(format.abr).toBeUndefined();
+  });
+});
+
+describe('mapDownloadProgress', () => {
+  it('maps a full progress payload', () => {
+    const progress = mapDownloadProgress(
+      {
+        status: 'downloading',
+        phase: 'downloading',
+        percent: 50,
+        downloadedBytes: 100,
+        totalBytes: 200,
+        speedBytesPerSecond: 10,
+        etaSeconds: 5,
+        filename: 'video.mp4',
+      },
+      'task-1'
+    );
+
+    expect(progress).not.toBeNull();
+    expect(progress?.taskId).toBe('task-1');
+    expect(progress?.status).toBe('downloading');
+    expect(progress?.percent).toBe(50);
+    expect(progress?.filename).toBe('video.mp4');
+  });
+
+  it('normalizes phase values', () => {
+    expect(mapDownloadProgress({ phase: 'extracting' }, 't')?.phase).toBe('extracting');
+    expect(mapDownloadProgress({ phase: 'processing' }, 't')?.phase).toBe('processing');
+    expect(mapDownloadProgress({ phase: 'unknown' }, 't')?.phase).toBe('downloading');
+  });
+
+  it('returns null for non-object payloads', () => {
+    expect(mapDownloadProgress(null, 't')).toBeNull();
+    expect(mapDownloadProgress('downloading', 't')).toBeNull();
+  });
+
+  it('never returns NaN - missing numbers become undefined', () => {
+    const progress = mapDownloadProgress({ percent: NaN, etaSeconds: 'bad' }, 't');
+    expect(progress?.percent).toBeUndefined();
+    expect(progress?.etaSeconds).toBeUndefined();
+  });
+});

package/src/__tests__/serializers.test.ts

@@ -0,0 +1,72 @@
+import { YtDlpError } from '../errors';
+import { serializeDownloadOptions, serializeExtractOptions } from '../serializers';
+
+describe('serializeDownloadOptions', () => {
+  it('sends url and format through', () => {
+    const out = serializeDownloadOptions({
+      url: 'https://x.test/v',
+      format: 'bestvideo+bestaudio',
+    });
+    expect(out.url).toBe('https://x.test/v');
+    expect(out.format).toBe('bestvideo+bestaudio');
+  });
+
+  it('passes ffmpeg.location through', () => {
+    const out = serializeDownloadOptions({
+      url: 'https://x.test/v',
+      format: 'bestvideo+bestaudio',
+      ffmpeg: { location: '/data/user/0/com.app/files/ffmpeg' },
+    });
+    expect(out.ffmpeg).toEqual({ location: '/data/user/0/com.app/files/ffmpeg' });
+  });
+
+  it('trims ffmpeg.location whitespace', () => {
+    const out = serializeDownloadOptions({
+      url: 'https://x.test/v',
+      ffmpeg: { location: '  /data/ffmpeg  ' },
+    });
+    expect(out.ffmpeg).toEqual({ location: '/data/ffmpeg' });
+  });
+
+  it('throws PROCESSING_FAILED for a blank ffmpeg.location', () => {
+    expect(() =>
+      serializeDownloadOptions({ url: 'https://x.test/v', ffmpeg: { location: '   ' } })
+    ).toThrow(YtDlpError);
+    try {
+      serializeDownloadOptions({ url: 'https://x.test/v', ffmpeg: { location: '   ' } });
+    } catch (error) {
+      expect((error as YtDlpError).code).toBe('PROCESSING_FAILED');
+    }
+  });
+
+  it('omits ffmpeg when not provided', () => {
+    const out = serializeDownloadOptions({ url: 'https://x.test/v' });
+    expect(out.ffmpeg).toBeUndefined();
+  });
+
+  it('passes merge through', () => {
+    expect(serializeDownloadOptions({ url: 'u', merge: true }).merge).toBe(true);
+    expect(serializeDownloadOptions({ url: 'u' }).merge).toBeUndefined();
+  });
+});
+
+describe('serializeExtractOptions', () => {
+  it('returns an empty object when no options are given', () => {
+    expect(serializeExtractOptions(undefined)).toEqual({});
+    expect(serializeExtractOptions({})).toEqual({});
+  });
+
+  it('merges a custom User-Agent into headers', () => {
+    const out = serializeExtractOptions({ userAgent: 'UA/1.0' });
+    expect(out.headers).toEqual({ 'User-Agent': 'UA/1.0' });
+  });
+
+  it('passes headers and cookies through', () => {
+    const out = serializeExtractOptions({
+      headers: { Referer: 'https://x.test' },
+      cookies: { source: 'file', path: '/data/cookies.txt' },
+    });
+    expect(out.headers).toEqual({ Referer: 'https://x.test' });
+    expect(out.cookies).toEqual({ path: '/data/cookies.txt' });
+  });
+});

package/src/constants.ts

@@ -1,7 +1,9 @@
 /**
  * Package-level constants.
  */
-export const LIBRARY_VERSION = '0.1.0';
+import pkg from '../package.json';
+
+export const LIBRARY_VERSION = pkg.version;
 
 export const SUPPORTED_PLATFORM = 'android';
 

package/src/downloadTask.ts

@@ -76,6 +76,14 @@ export class YtDlpDownloadTask implements DownloadTask {
     await this.native.cancelDownload(this.id);
   }
 
+  async pause(): Promise<boolean> {
+    return this.native.pauseDownload(this.id);
+  }
+
+  async resume(): Promise<boolean> {
+    return this.native.resumeDownload(this.id);
+  }
+
   async getStatus(): Promise<DownloadStatus> {
     if (this.finalized) return this.currentStatus;
     const info = await this.native.getDownloadStatus(this.id);
@@ -144,6 +152,7 @@ function mapStatusInfo(
 function phaseOf(status: DownloadStatus): DownloadProgress['phase'] {
   switch (status) {
     case 'downloading':
+    case 'paused':
       return 'downloading';
     case 'completed':
     case 'processing':

package/src/errors.ts

@@ -109,6 +109,9 @@ export function normalizeExtractionError(
   ) {
     return new YtDlpError('NETWORK_ERROR', base.message, { cause: base.cause });
   }
+  if (message.includes('age') || message.includes('mature') || message.includes('under 18')) {
+    return new YtDlpError('AGE_RESTRICTED', base.message, { cause: base.cause });
+  }
   if (
     message.includes('sign in to confirm') ||
     message.includes('log in') ||
@@ -119,9 +122,6 @@ export function normalizeExtractionError(
   if (message.includes('private') || message.includes('members-only')) {
     return new YtDlpError('PRIVATE_CONTENT', base.message, { cause: base.cause });
   }
-  if (message.includes('age') || message.includes('mature') || message.includes('under 18')) {
-    return new YtDlpError('AGE_RESTRICTED', base.message, { cause: base.cause });
-  }
   if (
     message.includes('geographic') ||
     message.includes('geo-') ||

package/src/index.ts

@@ -1,4 +1,4 @@
-import { cancel, download, extractInfo, getFormats, getVersion } from './YtDlp';
+import { cancel, download, extractInfo, getFormats, getVersion, pause, resume } from './YtDlp';
 import { YtDlpError } from './errors';
 
 export type * from './types';
@@ -10,6 +10,8 @@ export const YtDlp = {
   getFormats,
   download,
   cancel,
+  pause,
+  resume,
 };
 
 export { YtDlpError };

package/src/mappers.ts

@@ -88,8 +88,8 @@ export function mapFormat(raw: unknown): Format {
  * `DownloadProgress`, replacing any non-finite numbers with `undefined`.
  */
 export function mapDownloadProgress(raw: unknown, taskId: string): DownloadProgress | null {
-  const progress = asRecord(raw);
-  if (!progress) return null;
+  if (typeof raw !== 'object' || raw === null) return null;
+  const progress = raw as RawRecord;
 
   const percent = numberOf(progress.percent);
   const phaseRaw = stringOf(progress.phase);
@@ -114,6 +114,7 @@ function statusOf(value: unknown): DownloadProgress['status'] {
     case 'extracting':
     case 'downloading':
     case 'processing':
+    case 'paused':
     case 'completed':
     case 'cancelled':
     case 'failed':

package/src/serializers.ts

@@ -0,0 +1,78 @@
+/**
+ * Pure serializers that translate public options into the plain map sent to
+ * the native layer. Kept free of native imports so they can be unit-tested
+ * (AGENTS.md §49, §41).
+ */
+import { YtDlpError } from './errors';
+import type { CookieOptions, DownloadOptions, ExtractOptions } from './types';
+
+export function serializeExtractOptions(
+  options: ExtractOptions | undefined
+): Record<string, unknown> {
+  if (!options) return {};
+  const out: Record<string, unknown> = {};
+  if (options.cookies) out.cookies = serializeCookies(options.cookies);
+  if (options.proxy) out.proxy = options.proxy;
+  if (options.userAgent || options.headers) {
+    const headers: Record<string, string> = { ...(options.headers ?? {}) };
+    if (options.userAgent) headers['User-Agent'] = options.userAgent;
+    out.headers = headers;
+  }
+  return out;
+}
+
+export function serializeDownloadOptions(options: DownloadOptions): Record<string, unknown> {
+  const out: Record<string, unknown> = { url: options.url };
+  if (options.format) out.format = options.format;
+  if (options.output) {
+    const output: Record<string, unknown> = {};
+    if (options.output.directory) output.directory = options.output.directory;
+    if (options.output.filename) output.filename = options.output.filename;
+    if (Object.keys(output).length > 0) out.output = output;
+  }
+  if (options.merge != null) out.merge = options.merge;
+  if (options.ffmpeg?.location) {
+    const location = options.ffmpeg.location.trim();
+    if (!location) {
+      throw new YtDlpError('PROCESSING_FAILED', 'ffmpeg.location must not be empty.');
+    }
+    out.ffmpeg = { location };
+  }
+  if (options.cookies) out.cookies = serializeCookies(options.cookies);
+  if (options.userAgent || options.headers) {
+    const headers: Record<string, string> = { ...(options.headers ?? {}) };
+    if (options.userAgent) headers['User-Agent'] = options.userAgent;
+    out.headers = headers;
+  }
+  if (options.referer) out.referer = options.referer;
+  if (options.proxy) out.proxy = options.proxy;
+  if (options.playlist) {
+    const playlist: Record<string, unknown> = {};
+    if (options.playlist.enabled != null) playlist.enabled = options.playlist.enabled;
+    if (options.playlist.start != null) playlist.start = options.playlist.start;
+    if (options.playlist.end != null) playlist.end = options.playlist.end;
+    if (Object.keys(playlist).length > 0) out.playlist = playlist;
+  }
+  if (options.network) {
+    const network: Record<string, unknown> = {};
+    if (options.network.timeout != null) network.timeout = options.network.timeout;
+    if (options.network.retries != null) network.retries = options.network.retries;
+    if (Object.keys(network).length > 0) out.network = network;
+  }
+  if (options.subtitles) {
+    const subtitles: Record<string, unknown> = {};
+    if (options.subtitles.enabled != null) subtitles.enabled = options.subtitles.enabled;
+    if (options.subtitles.languages?.length) subtitles.languages = options.subtitles.languages;
+    if (options.subtitles.autoGenerated != null)
+      subtitles.autoGenerated = options.subtitles.autoGenerated;
+    if (Object.keys(subtitles).length > 0) out.subtitles = subtitles;
+  }
+  return out;
+}
+
+export function serializeCookies(cookies: CookieOptions): Record<string, unknown> {
+  if (cookies.source === 'file' && cookies.path) {
+    return { path: cookies.path };
+  }
+  throw new YtDlpError('INVALID_URL', 'Cookies must reference a cookies file path.');
+}

package/src/types.ts

@@ -7,7 +7,14 @@
 import type { YtDlpError } from './errors';
 
 export type DownloadStatus =
-  'queued' | 'extracting' | 'downloading' | 'processing' | 'completed' | 'cancelled' | 'failed';
+  | 'queued'
+  | 'extracting'
+  | 'downloading'
+  | 'processing'
+  | 'paused'
+  | 'completed'
+  | 'cancelled'
+  | 'failed';
 
 export type DownloadPhase = 'extracting' | 'downloading' | 'processing';
 
@@ -106,6 +113,21 @@ export interface NetworkOptions {
   retries?: number;
 }
 
+/**
+ * Optional FFmpeg integration (see issue #2). The package does **not** bundle
+ * FFmpeg — yt-dlp needs a real executable to merge separate video+audio
+ * streams (`bestvideo+bestaudio`), extract/re-encode audio, or embed metadata
+ * and thumbnails. Point `location` at an ffmpeg binary already on the device.
+ */
+export interface FfmpegOptions {
+  /**
+   * Absolute filesystem path to an `ffmpeg` executable, or to a directory
+   * that contains one. yt-dlp spawns the binary from here during
+   * post-processing. An in-process JNI wrapper (e.g. FFmpegKit) is not enough.
+   */
+  location: string;
+}
+
 export interface PlaylistOptions {
   enabled?: boolean;
   start?: number;
@@ -127,7 +149,17 @@ export interface DownloadOptions {
   /** Raw yt-dlp format expression, e.g. `best`, `bestvideo+bestaudio`. */
   format?: string;
   output?: OutputOptions;
+  /**
+   * Set to `true` to request merging (e.g. with `format: 'bestvideo+bestaudio'`).
+   * Merging requires FFmpeg — see `ffmpeg`.
+   */
   merge?: boolean;
+  /**
+   * Optional FFmpeg integration. When unset, FFmpeg-dependent features are
+   * rejected with `PROCESSING_FAILED`. When set, `bestvideo+bestaudio` and
+   * other post-processing become available.
+   */
+  ffmpeg?: FfmpegOptions;
   subtitles?: SubtitleOptions;
   cookies?: CookieOptions;
   /** Additional HTTP headers. Validated; secrets are never logged. */
@@ -188,6 +220,20 @@ export interface Subscription {
 export interface DownloadTask {
   id: string;
   cancel(): Promise<void>;
+  /**
+   * Pause an in-flight download. yt-dlp aborts on the next progress tick and
+   * leaves its `.part` file on disk; the task remains registered with status
+   * `paused`. Resolves `false` if the task is unknown, already paused, or
+   * already finished.
+   */
+  pause(): Promise<boolean>;
+  /**
+   * Resume a paused download with the exact same options. yt-dlp continues
+   * from the `.part` file by default (byte-range where the source supports it,
+   * otherwise the file restarts). Resolves `false` if the task is unknown or
+   * not paused.
+   */
+  resume(): Promise<boolean>;
   getStatus(): Promise<DownloadStatus>;
   getProgress(): Promise<DownloadProgress | null>;
   addListener(event: 'progress', listener: (progress: DownloadProgress) => void): Subscription;