react-native-video-trim 7.1.0 → 8.0.0

package/src/NativeVideoTrim.ts

@@ -26,6 +26,14 @@ export interface BaseOptions {
    * happens regardless of this flag, so precise trimming comes for free in that case.
    */
   enablePreciseTrimming: boolean;
+  /** When `true`, strips the audio track from the output. Default `false`. */
+  removeAudio: boolean;
+  /**
+   * Playback speed multiplier applied during export. `1.0` is normal speed,
+   * `2.0` is double speed, `0.5` is half speed. Valid range: 0.25–4.0.
+   * When not `1.0`, re-encoding is forced regardless of `enablePreciseTrimming`.
+   */
+  speed: number;
 }
 
 /**
@@ -129,6 +137,16 @@ export interface EditorConfig extends BaseOptions {
    * `"light"` uses a white background with black icons/text and white trimmer-handle chevrons.
    */
   theme?: string;
+  /** Color of the audio waveform bars as a `processColor` value. */
+  waveformColor?: number;
+  /** Background color behind the audio waveform bars as a `processColor` value. */
+  waveformBackgroundColor?: number;
+  /** Width of each waveform bar in dp/pt (default: `3`). */
+  waveformBarWidth?: number;
+  /** Gap between waveform bars in dp/pt (default: `2`). */
+  waveformBarGap?: number;
+  /** Corner radius of waveform bars in dp/pt (default: `1.5`). */
+  waveformBarCornerRadius?: number;
 }
 
 /**
@@ -169,6 +187,143 @@ export interface TrimResult {
   success: boolean;
 }
 
+/**
+ * Options for extracting a single frame from a video.
+ */
+export interface FrameExtractionOptions {
+  /** Timestamp in milliseconds at which to extract the frame. */
+  time: number;
+  /** Output image format: `"jpeg"` (default) or `"png"`. */
+  format: string;
+  /** JPEG compression quality from 0–100. Default `80`. Ignored for PNG. */
+  quality: number;
+  /** Maximum width in pixels. Height is auto-calculated to preserve aspect ratio. `-1` for original. */
+  maxWidth: number;
+  /** Maximum height in pixels. Width is auto-calculated to preserve aspect ratio. `-1` for original. */
+  maxHeight: number;
+}
+
+/**
+ * Result returned by {@link Spec.getFrameAt}.
+ */
+export interface FrameResult {
+  /** Absolute path to the extracted image file. */
+  outputPath: string;
+}
+
+/**
+ * Options for extracting the audio track from a video file.
+ */
+export interface ExtractAudioOptions {
+  /** Output audio file extension (e.g. `"mp3"`, `"m4a"`, `"wav"`). Default `"mp3"`. */
+  outputExt: string;
+}
+
+/**
+ * Result returned by {@link Spec.extractAudio}.
+ */
+export interface ExtractAudioResult {
+  /** Absolute path to the extracted audio file. */
+  outputPath: string;
+  /** Duration of the audio in milliseconds. */
+  duration: number;
+}
+
+/**
+ * Options for compressing a video file.
+ */
+export interface CompressOptions {
+  /**
+   * Quality preset: `"low"` (smallest file), `"medium"` (balanced), `"high"` (best quality).
+   * Maps to CRF 28, 23, 18 respectively. Ignored when `bitrate` is set.
+   */
+  quality: string;
+  /** Explicit target bitrate in bits per second. Overrides `quality` when set. `-1` to use quality preset. */
+  bitrate: number;
+  /** Target width in pixels. `-1` to keep original. Height is auto-calculated to preserve aspect ratio. */
+  width: number;
+  /** Target height in pixels. `-1` to keep original. Width is auto-calculated to preserve aspect ratio. */
+  height: number;
+  /** Target frame rate. `-1` to keep original. */
+  frameRate: number;
+  /** Output file extension (e.g. `"mp4"`). Default `"mp4"`. */
+  outputExt: string;
+  /** When `true`, strips the audio track from the output. Default `false`. */
+  removeAudio: boolean;
+}
+
+/**
+ * Result returned by {@link Spec.compress}.
+ */
+export interface CompressResult {
+  /** Absolute path to the compressed output file. */
+  outputPath: string;
+}
+
+/**
+ * Options for converting a video segment to an animated GIF.
+ */
+export interface GifOptions {
+  /** Start time in milliseconds. Default `0`. */
+  startTime: number;
+  /** End time in milliseconds. Default `-1` (end of video). */
+  endTime: number;
+  /** Frame rate of the GIF. Default `10`. */
+  fps: number;
+  /** Width in pixels. Height is auto-calculated to preserve aspect ratio. `-1` for original. */
+  width: number;
+}
+
+/**
+ * Result returned by {@link Spec.toGif}.
+ */
+export interface GifResult {
+  /** Absolute path to the generated GIF file. */
+  outputPath: string;
+}
+
+/**
+ * Options for merging multiple media files into one.
+ */
+export interface MergeOptions {
+  /** Output file extension (e.g. `"mp4"`, `"wav"`). Default `"mp4"`. */
+  outputExt: string;
+}
+
+/**
+ * Result returned by {@link Spec.merge}.
+ */
+export interface MergeResult {
+  /** Absolute path to the merged output file. */
+  outputPath: string;
+  /** Total duration of the merged file in milliseconds. */
+  duration: number;
+}
+
+/**
+ * Result returned by {@link Spec.saveToPhoto}.
+ */
+export interface SaveToPhotoResult {
+  /** Whether the file was saved to the photo library successfully. */
+  success: boolean;
+}
+
+/**
+ * Result returned by {@link Spec.saveToDocuments}.
+ */
+export interface SaveToDocumentsResult {
+  /** Whether the file was saved to documents successfully. */
+  success: boolean;
+}
+
+/**
+ * Result returned by {@link Spec.share}.
+ */
+export interface ShareResult {
+  /** Whether the user completed the share action. */
+  success: boolean;
+}
+
 /**
  * TurboModule spec for the native VideoTrim module.
  */
@@ -187,6 +342,22 @@ export interface Spec extends TurboModule {
   isValidFile(url: string): Promise<FileValidationResult>;
   /** Perform a headless trim (no UI) on the given URL with the specified options. */
   trim(url: string, options: TrimOptions): Promise<TrimResult>;
+  /** Extract a single frame from a video at the specified timestamp. */
+  getFrameAt(url: string, options: FrameExtractionOptions): Promise<FrameResult>;
+  /** Extract the audio track from a video file into a separate audio file. */
+  extractAudio(url: string, options: ExtractAudioOptions): Promise<ExtractAudioResult>;
+  /** Compress a video file to reduce its size. */
+  compress(url: string, options: CompressOptions): Promise<CompressResult>;
+  /** Convert a video segment to an animated GIF. */
+  toGif(url: string, options: GifOptions): Promise<GifResult>;
+  /** Merge multiple media files into a single file. Headless only, no editor UI. */
+  merge(urls: ReadonlyArray<string>, options: MergeOptions): Promise<MergeResult>;
+  /** Save a file to the device's photo library. Requires photo library permission. */
+  saveToPhoto(filePath: string): Promise<SaveToPhotoResult>;
+  /** Present the system document picker to save a file to the user's chosen location. */
+  saveToDocuments(filePath: string): Promise<SaveToDocumentsResult>;
+  /** Open the system share sheet for a file. */
+  share(filePath: string): Promise<ShareResult>;
 
   /** Emitted when the trim operation starts. */
   readonly onStartTrimming: EventEmitter<void>;

package/src/index.tsx

@@ -2,8 +2,21 @@ import VideoTrimNewArch from './NativeVideoTrim';
 import VideoTrimOldArch from './OldArch';
 import type {
   BaseOptions,
+  CompressOptions,
+  CompressResult,
   EditorConfig,
+  ExtractAudioOptions,
+  ExtractAudioResult,
   FileValidationResult,
+  FrameExtractionOptions,
+  FrameResult,
+  GifOptions,
+  GifResult,
+  MergeOptions,
+  MergeResult,
+  SaveToDocumentsResult,
+  SaveToPhotoResult,
+  ShareResult,
   TrimOptions,
   TrimResult,
 } from './NativeVideoTrim';
@@ -21,6 +34,64 @@ function createBaseOptions(overrides: Partial<BaseOptions> = {}): BaseOptions {
     removeAfterSavedToPhoto: false,
     removeAfterFailedToSavePhoto: false,
     enablePreciseTrimming: false,
+    removeAudio: false,
+    speed: 1.0,
+    ...overrides,
+  };
+}
+
+function createCompressOptions(
+  overrides: Partial<CompressOptions> = {}
+): CompressOptions {
+  return {
+    quality: 'medium',
+    bitrate: -1,
+    width: -1,
+    height: -1,
+    frameRate: -1,
+    outputExt: 'mp4',
+    removeAudio: false,
+    ...overrides,
+  };
+}
+
+function createFrameExtractionOptions(
+  overrides: Partial<FrameExtractionOptions> = {}
+): FrameExtractionOptions {
+  return {
+    time: 0,
+    format: 'jpeg',
+    quality: 80,
+    maxWidth: -1,
+    maxHeight: -1,
+    ...overrides,
+  };
+}
+
+function createExtractAudioOptions(
+  overrides: Partial<ExtractAudioOptions> = {}
+): ExtractAudioOptions {
+  return {
+    outputExt: 'm4a',
+    ...overrides,
+  };
+}
+
+function createGifOptions(overrides: Partial<GifOptions> = {}): GifOptions {
+  return {
+    startTime: 0,
+    endTime: -1,
+    fps: 10,
+    width: -1,
+    ...overrides,
+  };
+}
+
+function createMergeOptions(
+  overrides: Partial<MergeOptions> = {}
+): MergeOptions {
+  return {
+    outputExt: 'mp4',
     ...overrides,
   };
 }
@@ -73,6 +144,11 @@ function createEditorConfig(
     alertOnFailMessage:
       'Fail to load media. Possibly invalid file or no network connection',
     alertOnFailCloseText: 'Close',
+    waveformColor: processColor('white') as number,
+    waveformBackgroundColor: processColor('#3478F6') as number,
+    waveformBarWidth: 3,
+    waveformBarGap: 2,
+    waveformBarCornerRadius: 1.5,
     ...createBaseOptions(overrides),
     ...overrides,
   };
@@ -98,14 +174,29 @@ function createTrimOptions(overrides: Partial<TrimOptions> = {}): TrimOptions {
 export function showEditor(
   filePath: string,
   config: Partial<
-    Omit<EditorConfig, 'headerTextColor' | 'trimmerColor' | 'handleIconColor'>
+    Omit<
+      EditorConfig,
+      | 'headerTextColor'
+      | 'trimmerColor'
+      | 'handleIconColor'
+      | 'waveformColor'
+      | 'waveformBackgroundColor'
+    >
   > & {
     headerTextColor?: string;
     trimmerColor?: string;
     handleIconColor?: string;
+    waveformColor?: string;
+    waveformBackgroundColor?: string;
   }
 ): void {
-  const { headerTextColor, trimmerColor, handleIconColor } = config;
+  const {
+    headerTextColor,
+    trimmerColor,
+    handleIconColor,
+    waveformColor,
+    waveformBackgroundColor,
+  } = config;
   const isLight = config.theme === 'light';
   const _headerTextColor = processColor(
     headerTextColor || (isLight ? 'black' : 'white')
@@ -114,6 +205,10 @@ export function showEditor(
   const _handleIconColor = processColor(
     handleIconColor || (isLight ? 'white' : 'black')
   );
+  const _waveformColor = processColor(waveformColor || 'white');
+  const _waveformBackgroundColor = processColor(
+    waveformBackgroundColor || '#3478F6'
+  );
 
   VideoTrim.showEditor(
     filePath,
@@ -122,6 +217,8 @@ export function showEditor(
       headerTextColor: _headerTextColor as any,
       trimmerColor: _trimmerColor as any,
       handleIconColor: _handleIconColor as any,
+      waveformColor: _waveformColor as any,
+      waveformBackgroundColor: _waveformBackgroundColor as any,
     })
   );
 }
@@ -188,5 +285,117 @@ export function trim(
   return VideoTrim.trim(url, createTrimOptions(options));
 }
 
+/**
+ * Extract a single frame from a video at a given timestamp
+ *
+ * @param {string} url: absolute non-empty file path
+ * @param {Partial<FrameExtractionOptions>} options: extraction options
+ * @returns {Promise<FrameResult>} A **Promise** which resolves to the FrameResult
+ */
+export function getFrameAt(
+  url: string,
+  options: Partial<FrameExtractionOptions> = {}
+): Promise<FrameResult> {
+  return VideoTrim.getFrameAt(url, createFrameExtractionOptions(options));
+}
+
+/**
+ * Extract the audio track from a video file
+ *
+ * @param {string} url: absolute non-empty file path
+ * @param {Partial<ExtractAudioOptions>} options: extraction options
+ * @returns {Promise<ExtractAudioResult>} A **Promise** which resolves to the result
+ */
+export function extractAudio(
+  url: string,
+  options: Partial<ExtractAudioOptions> = {}
+): Promise<ExtractAudioResult> {
+  return VideoTrim.extractAudio(url, createExtractAudioOptions(options));
+}
+
+/**
+ * Compress a video file to reduce its size
+ *
+ * @param {string} url: absolute non-empty file path
+ * @param {Partial<CompressOptions>} options: compression options
+ * @returns {Promise<CompressResult>} A **Promise** which resolves to the result
+ */
+export function compress(
+  url: string,
+  options: Partial<CompressOptions> = {}
+): Promise<CompressResult> {
+  return VideoTrim.compress(url, createCompressOptions(options));
+}
+
+/**
+ * Convert a video segment to an animated GIF
+ *
+ * @param {string} url: absolute non-empty file path
+ * @param {Partial<GifOptions>} options: GIF conversion options
+ * @returns {Promise<GifResult>} A **Promise** which resolves to the result
+ */
+export function toGif(
+  url: string,
+  options: Partial<GifOptions> = {}
+): Promise<GifResult> {
+  return VideoTrim.toGif(url, createGifOptions(options));
+}
+
+/**
+ * Merge multiple media files into a single file (headless, no UI)
+ *
+ * @param {string[]} urls: array of file paths to merge in order
+ * @param {Partial<MergeOptions>} options: merge options
+ * @returns {Promise<MergeResult>} A **Promise** which resolves to the result
+ */
+export function merge(
+  urls: string[],
+  options: Partial<MergeOptions> = {}
+): Promise<MergeResult> {
+  if (!urls?.length) {
+    throw new Error('URLs array cannot be empty!');
+  }
+  return VideoTrim.merge(urls, createMergeOptions(options));
+}
+
+/**
+ * Save a file to the device's photo library
+ *
+ * @param {string} filePath: absolute path to the file
+ * @returns {Promise<SaveToPhotoResult>} A **Promise** which resolves to the result
+ */
+export function saveToPhoto(filePath: string): Promise<SaveToPhotoResult> {
+  if (!filePath?.trim().length) {
+    throw new Error('File path cannot be empty!');
+  }
+  return VideoTrim.saveToPhoto(filePath);
+}
+
+/**
+ * Present the system document picker to save a file
+ *
+ * @param {string} filePath: absolute path to the file
+ * @returns {Promise<SaveToDocumentsResult>} A **Promise** which resolves to the result
+ */
+export function saveToDocuments(filePath: string): Promise<SaveToDocumentsResult> {
+  if (!filePath?.trim().length) {
+    throw new Error('File path cannot be empty!');
+  }
+  return VideoTrim.saveToDocuments(filePath);
+}
+
+/**
+ * Open the system share sheet for a file
+ *
+ * @param {string} filePath: absolute path to the file
+ * @returns {Promise<ShareResult>} A **Promise** which resolves to the result
+ */
+export function share(filePath: string): Promise<ShareResult> {
+  if (!filePath?.trim().length) {
+    throw new Error('File path cannot be empty!');
+  }
+  return VideoTrim.share(filePath);
+}
+
 export * from './NativeVideoTrim';
 export default VideoTrim;