Compression
compress(inputUri, options?, onProgress?): Promise<string> exports an MP4 and resolves after the file is complete. It uses H.264 by default and AAC audio when present and not muted. Video is re-encoded. Without options, source dimensions are retained with even-pixel rounding and a source-based target bitrate.
Option | Default | Behavior |
|---|---|---|
| Adaptive |
|
| Source width | Maximum displayed width, 2–16384, integer pixels. |
| Source height | Maximum displayed height, 2–16384, integer pixels. |
| Adaptive | Target video bitrate, positive 32-bit integer. Encoder output may vary. |
|
|
|
| Source rate | Frame-rate target, 1–240. Drops frames without duplicating them; actual rate can vary with input timestamps. |
|
| Start of the retained clip, in seconds. Must precede the source's end. |
| Source end | End of the retained clip. Must exceed |
|
| Remove all audio. Audio options have no effect for muted or silent sources. |
|
| AAC target bitrate, 8000–320000. |
| iOS: | AAC sample rate: 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, or 48000 Hz. |
| iOS: |
|
| Unique name | A filename ending in |
|
| Replace an existing cache output only after successful export. |
|
| Progress notification interval in milliseconds, integer 50–10000. |
|
| iOS optimizes file layout; Android attempts a streamable MP4 layout. |
Both size limits form a bounding box. Aspect ratio and orientation are preserved without upscaling; encoded video dimensions round down to even pixels. Frame-rate caps drop frames without duplicating them. Actual bitrate and frame rate can vary with input timestamps and device encoders.
Trimming uses the source timeline. startTime must be before the effective end; endTime must exceed startTime (default 0), and values beyond the source duration are clamped. A numerically valid time can still lie outside the source and reject.
When bitrate is omitted, the target is the smaller of the source bitrate (or a 2000000 fallback) and max(250000, encodedWidth * encodedHeight * 4). iOS uses the video-track source bitrate; Android uses container bitrate. This target calculation does not guarantee file size.
optimizeForNetworkUse controls MP4 layout: AVFoundation optimization on iOS and an attempted streamable layout on Android. It does not upload media or guarantee playback in every player.
Runtime validation
Value | Accepted range or set | Integer required? |
|---|---|---|
Compression | 2–16384, inclusive | Yes |
Compression | 1–2147483647, inclusive | Yes |
| 1–240, inclusive | No; fractional targets are accepted |
| 0–2147483 seconds, inclusive | No |
| 8000–320000 bits per second, inclusive | Yes |
| 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000 Hz | The listed values only |
| 1 or 2 | Yes |
| 50–10000 milliseconds, inclusive | Yes |
Thumbnail | 0–2147483 seconds, inclusive, and before source end | No |
Thumbnail | 2–16384, inclusive | Yes |
Thumbnail | 0–1, inclusive | No |
All numeric values must be finite numbers. Numeric strings, NaN, infinities, and out-of-range values reject. Compression quality accepts only low, medium, or high; codec accepts h264 or hevc. Boolean options require booleans. inputUri must be a non-blank string; native code then checks the scheme, readability, and media.
Output names must be non-blank, end in .mp4 (compression) or .jpg (thumbnail), case insensitively, and have no slash, backslash, or character with a code below 32. Supply a filename, not a full path. Valid options can still exceed a device encoder's capabilities and reject.