@capgo/capacitor-ffmpeg

Re-encode videos and convert images on the device from your Capacitor app, with FFmpeg-based native code. Shrink uploads and normalize media formats without a server.

• Video re-encode: reencodeVideo() queues a job and reports progress events.
• Image conversion: convertImage() converts a still image to another format.
• Audio conversion: convertAudio() where the platform supports it.
• Capability matrix: getCapabilities() tells you which operations the current platform supports.
• Platforms: iOS and Android. iOS uses AVFoundation with a native FFmpeg core, Android uses FFmpegKit and Media3. Not available on web. The feature set is intentionally smaller than upstream FFmpeg.

The most complete doc is available here: https://capgo.app/docs/plugins/ffmpeg/

Project roadmap: ROADMAP.md Feature matrix: FEATURE_MATRIX.md Fixture strategy: test/fixtures/README.md Test inventory: test/TEST_INVENTORY.md

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-ffmpeg` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-ffmpeg
bunx cap sync

• getCapabilities()
• reencodeVideo(...)
• convertImage(...)
• convertAudio(...)
• addListener('progress', ...)
• getPluginVersion()
• Interfaces
• Type Aliases

getCapabilities() => Promise<FFmpegCapabilitiesResult>

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

Returns: Promise<FFmpegCapabilitiesResult>

reencodeVideo(options: ReencodeVideoOptions) => Promise<FFmpegAcceptedJob>

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 accepts a queued job and reports lifecycle via progress. Web currently rejects with UNIMPLEMENTED.

Returns: Promise<FFmpegAcceptedJob>

convertImage(options: ConvertImageOptions) => Promise<ConvertImageResult>

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.

Returns: Promise<ConvertImageResult>

convertAudio(options: ConvertAudioOptions) => Promise<ConvertAudioResult>

Convert audio into another container or codec.

iOS currently supports m4a and wav. Android supports m4a, mp3, wav, ogg, aac, and flac. Web currently rejects with UNIMPLEMENTED.

Returns: Promise<ConvertAudioResult>

addListener(eventName: 'progress', listenerFunc: (event: FFmpegProgressEvent) => void) => Promise<PluginListenerHandle>

Listen for media job progress.

Returns: Promise<PluginListenerHandle>

getPluginVersion() => Promise<PluginVersionResult>

Get the plugin package version reported by the current platform implementation.

Returns: Promise<PluginVersionResult>

'available' | 'experimental' | 'unimplemented' | 'unavailable'

'webp' | 'jpeg' | 'png'

'm4a' | 'mp3' | 'wav' | 'ogg' | 'aac' | 'flac'

'running' | 'completed' | 'failed'