@capgo/capacitor-ffmpeg
May 11, 2026 · View on GitHub
This plugin exposes FFmpeg capabilities to Capacitor. The implementation is still early, and the supported feature set is intentionally smaller than upstream FFmpeg.
Documentation
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
Compatibility
| Plugin version | Capacitor compatibility | Maintained |
|---|---|---|
| v8.*.* | v8.*.* | ✅ |
| v7.*.* | v7.*.* | On demand |
| v6.*.* | v6.*.* | ❌ |
| v5.*.* | v5.*.* | ❌ |
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.
Install
bun add @capgo/capacitor-ffmpeg
bunx cap sync
Supported today
| Capability | iOS | Android | Web | Notes |
|---|---|---|---|---|
getCapabilities | ✅ | ✅ | ✅ | Returns the runtime capability matrix so apps can check what is actually usable on the current platform. |
getPluginVersion | ✅ | ✅ | ✅ | Returns a { version } payload on every platform; use getCapabilities().platform for platform detection. |
reencodeVideo | ⚠️ Experimental | ❌ | ❌ | iOS accepts a queued job and reports lifecycle via progress; Android and web reject with UNIMPLEMENTED. |
convertImage | ✅ | ✅ | ❌ | iOS converts still images to jpeg or png; Android converts to webp, jpeg, or png; web rejects. |
convertAudio | ✅ | ❌ | ❌ | iOS converts audio to m4a; Android and web reject with UNIMPLEMENTED. |
Platform status
| Platform | Status | Notes |
|---|---|---|
| iOS | Early implementation | Current reference platform for media work. |
| Android | Partial native implementation | convertImage is native; the broader FFmpeg media engine and convertAudio still need to be implemented. |
| Web | Stub only | Media operations are intentionally unsupported right now. |
API
getCapabilities()
getCapabilities() => Promise<FFmpegCapabilitiesResult>
Return the machine-readable capability matrix for the current platform.
Returns: Promise<FFmpegCapabilitiesResult>
reencodeVideo(...)
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 and web currently reject with UNIMPLEMENTED.
| Param | Type |
|---|---|
options | ReencodeVideoOptions |
Returns: Promise<FFmpegAcceptedJob>
convertImage(...)
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.
| Param | Type |
|---|---|
options | ConvertImageOptions |
Returns: Promise<ConvertImageResult>
convertAudio(...)
convertAudio(options: ConvertAudioOptions) => Promise<ConvertAudioResult>
Convert audio into another container or codec.
iOS currently supports m4a.
Android and web currently reject with UNIMPLEMENTED.
| Param | Type |
|---|---|
options | ConvertAudioOptions |
Returns: Promise<ConvertAudioResult>
addListener('progress', ...)
addListener(eventName: 'progress', listenerFunc: (event: FFmpegProgressEvent) => void) => Promise<PluginListenerHandle>
Listen for media job progress.
| Param | Type |
|---|---|
eventName | 'progress' |
listenerFunc | (event: FFmpegProgressEvent) => void |
Returns: Promise<PluginListenerHandle>
getPluginVersion()
getPluginVersion() => Promise<PluginVersionResult>
Get the plugin package version reported by the current platform implementation.
Returns: Promise<PluginVersionResult>
Interfaces
FFmpegCapabilitiesResult
| Prop | Type |
|---|---|
platform | string |
features | FFmpegCapabilitiesFeatures |
FFmpegCapabilitiesFeatures
| Prop | Type |
|---|---|
getPluginVersion | FFmpegCapability |
getCapabilities | FFmpegCapability |
reencodeVideo | FFmpegCapability |
convertImage | FFmpegCapability |
convertAudio | FFmpegCapability |
progressEvents | FFmpegCapability |
probeMedia | FFmpegCapability |
generateThumbnail | FFmpegCapability |
extractAudio | FFmpegCapability |
remux | FFmpegCapability |
trim | FFmpegCapability |
FFmpegCapability
| Prop | Type |
|---|---|
status | FFmpegCapabilityStatus |
reason | string |
FFmpegAcceptedJob
| Prop | Type |
|---|---|
jobId | string |
status | 'queued' |
ReencodeVideoOptions
| Prop | Type |
|---|---|
inputPath | string |
outputPath | string |
width | number |
height | number |
bitrate | number |
ConvertImageResult
| Prop | Type |
|---|---|
outputPath | string |
format | ImageOutputFormat |
ConvertImageOptions
| Prop | Type | Description |
|---|---|---|
inputPath | string | |
outputPath | string | |
format | ImageOutputFormat | |
quality | number | Compression quality in the inclusive range 0.0..1.0. Native platforms reject values outside that range. |
ConvertAudioResult
| Prop | Type |
|---|---|
outputPath | string |
format | AudioOutputFormat |
ConvertAudioOptions
| Prop | Type |
|---|---|
inputPath | string |
outputPath | string |
format | AudioOutputFormat |
PluginListenerHandle
| Prop | Type |
|---|---|
remove | () => Promise<void> |
FFmpegProgressEvent
| Prop | Type | Description |
|---|---|---|
jobId | string | |
progress | number | Normalized progress as a floating-point value in the inclusive range 0.0..1.0. |
state | FFmpegProgressState | |
message | string | |
outputPath | string | |
fileId | string | Legacy alias kept for compatibility while callers migrate to jobId. |
PluginVersionResult
| Prop | Type |
|---|---|
version | string |
Type Aliases
FFmpegCapabilityStatus
'available' | 'experimental' | 'unimplemented' | 'unavailable'
ImageOutputFormat
'webp' | 'jpeg' | 'png'
AudioOutputFormat
'm4a'
FFmpegProgressState
'running' | 'completed' | 'failed'