Getting Started

Install

bun add @capgo/capacitor-ffmpeg
bunx cap sync

Import

import { CapacitorFFmpeg } from '@capgo/capacitor-ffmpeg';

API Overview

getCapabilities

Return the machine-readable capability matrix for the current platform.

import { CapacitorFFmpeg } from '@capgo/capacitor-ffmpeg';

await CapacitorFFmpeg.getCapabilities();

reencodeVideo

Queue a video re-encode job.

On iOS, the returned promise resolves when the native layer accepts the job. Final success or failure is delivered through the progress listener.

Android and web currently reject with UNIMPLEMENTED.

import { CapacitorFFmpeg } from '@capgo/capacitor-ffmpeg';

await CapacitorFFmpeg.reencodeVideo({} as ReencodeVideoOptions);

convertImage

Convert a still image into another format.

iOS currently supports jpeg and .png. Android currently supports .webp, jpeg, and .png. Web currently rejects with UNIMPLEMENTED.

import { CapacitorFFmpeg } from '@capgo/capacitor-ffmpeg';

await CapacitorFFmpeg.convertImage({} as ConvertImageOptions);

convertAudio

Convert audio into another container or codec.

iOS currently supports m4a. Android and web currently reject with UNIMPLEMENTED.

import { CapacitorFFmpeg } from '@capgo/capacitor-ffmpeg';

await CapacitorFFmpeg.convertAudio({} as ConvertAudioOptions);

Type Reference

FFmpegCapabilitiesResult

export interface FFmpegCapabilitiesResult {
  platform: string;
  features: FFmpegCapabilitiesFeatures;
}

ReencodeVideoOptions

export interface ReencodeVideoOptions {
  inputPath: string;
  outputPath: string;
  width: number;
  height: number;
  bitrate?: number;
}

FFmpegAcceptedJob

export interface FFmpegAcceptedJob {
  jobId: string;
  status: 'queued';
}

ConvertImageOptions

export interface ConvertImageOptions {
  inputPath: string;
  outputPath: string;
  format: ImageOutputFormat;
  /**
   * Compression quality in the inclusive range `0.0..1.0`.
   *
   * Native platforms reject values outside that range.
   */
  quality?: number;
}

ConvertImageResult

export interface ConvertImageResult {
  outputPath: string;
  format: ImageOutputFormat;
}

ConvertAudioOptions

export interface ConvertAudioOptions {
  inputPath: string;
  outputPath: string;
  format: AudioOutputFormat;
}

ConvertAudioResult

export interface ConvertAudioResult {
  outputPath: string;
  format: AudioOutputFormat;
}

FFmpegProgressEvent

export interface FFmpegProgressEvent {
  jobId: string;
  /**
   * Normalized progress as a floating-point value in the inclusive range `0.0..1.0`.
   */
  progress: number;
  state: FFmpegProgressState;
  message?: string;
  outputPath?: string;
  /**
   * Legacy alias kept for compatibility while callers migrate to `jobId`.
   */
  fileId?: string;
}

PluginVersionResult

export interface PluginVersionResult {
  version: string;
}

FFmpegCapabilitiesFeatures

export interface FFmpegCapabilitiesFeatures {
  getPluginVersion: FFmpegCapability;
  getCapabilities: FFmpegCapability;
  reencodeVideo: FFmpegCapability;
  convertImage: FFmpegCapability;
  convertAudio?: FFmpegCapability;
  progressEvents: FFmpegCapability;
  probeMedia: FFmpegCapability;
  generateThumbnail: FFmpegCapability;
  extractAudio: FFmpegCapability;
  remux: FFmpegCapability;
  trim: FFmpegCapability;
}

ImageOutputFormat

export type ImageOutputFormat = '.webp' | 'jpeg' | '.png';

AudioOutputFormat

export type AudioOutputFormat = 'm4a';

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.