Video Stabilization

AIBudsVideoStabilization is an optional post-processing plugin that converts a supported compound six-axis recording into a stabilized MP4 while preserving the downloaded source.

It is not an on-device camera setting and does not stabilize live preview. Processing begins after Media File Import produces a local file.

Animated flow map

Post-import stabilization pipeline

The downloaded original remains the durable fallback while eligible six-axis video moves through optional processing.

HImport

Downloaded Source

Keep the downloaded source as the durable fallback.

SEligibility

Inspect Recording

Check metadata and supported six-axis recording data.

↻Optional processor

Stabilize Video

Create a derivative without replacing the source.

✓Preferred output

Stabilized MP4

Prefer the verified stabilized output for playback.

↩Safe fallback

Use Original File

Use the original when processing is skipped or fails.

• Downloaded Sourcecontinues toInspect Recording
• Inspect RecordingeligibleStabilize Video
• Stabilize Videocontinues toStabilized MP4
• Inspect Recordingnot processedUse Original File
• Stabilize VideofailedUse Original File

↳Stabilization failure changes the derivative result, not the success of an already completed download.

Pipeline Boundary

AIBuds coordinates import and invokes a registered VideoStabilizationPlugin. AIBudsVideoStabilization supplies the built-in implementation. AIBudsAllInOne registers it during suite initialization; modular integrations must explicitly own registration.

The module also exposes VideoStabilizer for processing an already-local compound recording without a device transfer. Retain the returned VideoStabilizationTask until completion so the job can be cancelled.

Implement with AI Assistance

Build with AI

Implement this workflow with AI

Use the official Import Media from AIBuds skill to adapt this workflow to your app.

Read and follow https://docs-aibuds.github.io/skills/import-aibuds-media. Use it to implement Import Media from AIBuds in this iOS project and verify the result.

View official skill↗

Decide Where Processing Belongs

Use SDK-managed processing when import and stabilization should be one coordinated operation. Disable it when the product owns another local or server-side processor. Never decide eligibility from file extension alone; the plugin inspects the local file and MediaFileInfoModel.

Preserve the Source

The plugin contract must not replace or remove its input. On success prefer the derivative; otherwise use the downloaded original:

Swift

Swift

let playableURL = importedFile.stabilizedFileURL ?? importedFile.localFileURL

Objective-C

Objective-C

NSURL *playableURL = importedFile.stabilizedFileURL ?: importedFile.localFileURL;

Do not treat stabilization failure as download failure. Show transfer and stabilization as separate phases and retain per-file state.

Interpret Status

Status	Product meaning
notRequired	Not a six-axis file; use the original.
pending	Waiting for processing.
stabilized	Processing succeeded; prefer stabilizedFileURL.
pluginUnavailable	No plugin is registered; keep the original.
skipped	The plugin cannot process this file; keep the original.
failed	Processing failed; expose the error and keep the original when available.
disabled	The app chose to own processing.

See StabilizationStatus. Do not infer a missing status from output presence.

Quality and Resource Trade-offs

The built-in default configuration uses trimRatio = 0.1, derives bitrate when averageBitRate = 0, and selects automatic. Automatic mode prefers the lower-memory gyro/Metal engine and can fall back to AWEIS when gyro metadata or Metal is unavailable. The configuration also exposes calibrated focal length, axis mapping, sensor time offset, gyro smoothing, AWEIS radius, and console-output controls. More crop provides motion margin but removes image area; more bitrate costs storage and throughput. Validate custom settings across representative resolution, duration, motion, storage, and thermal conditions.

Process eligible files serially unless testing proves parallel work safe. Keep per-file progress (0.0...1.0) separate from batch index/count, throttle UI updates, and make cancellation idempotent. During processing the app may hold original, partial, and final files at once.

Retention Checklist

• The optional module and license resource are packaged.
• Modular initialization registers one intended plugin.
• All stabilization states are represented.
• Playback prefers stabilized output and falls back to original.
• Transfer, per-file processing, and batch completion remain distinct.
• Cancellation preserves usable output and originals.
• Long videos are tested for storage, memory, thermal load, and interruption.
• Temporary and retained media follow privacy and deletion policy.