@capgo/capacitor-ffmpeg

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

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

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

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	⚠️ Experimental	❌	iOS and Android accept a queued job and report lifecycle via progress; web rejects 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 and wav; Android converts to m4a, mp3, wav, ogg, aac, and flac; web rejects.

Platform status

Platform	Status	Notes
iOS	Early implementation	Current reference platform for media work.
Android	Partial native implementation	convertImage, convertAudio, and reencodeVideo are native; broader FFmpeg media engine parity is still in progress.
Web	Stub only	Media operations are intentionally unsupported right now.

API

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

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 accepts a queued job and reports lifecycle via progress. Web currently rejects 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 and wav. Android supports m4a, mp3, wav, ogg, aac, and flac. Web currently rejects 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	Description
inputPath	string
outputPath	string
format	AudioOutputFormat
bitrate	number	Target audio bitrate in bits per second. Ignored for lossless outputs such as wav and flac.

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' | 'mp3' | 'wav' | 'ogg' | 'aac' | 'flac'

FFmpegProgressState

'running' | 'completed' | 'failed'