Advanced Topics Video Stabilization

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.

Post-import stabilization pipeline

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

1. Downloaded Source — Keep the downloaded source as the durable fallback.
2. Inspect Recording — Check metadata and supported six-axis recording data.
3. Stabilize Video — Create a derivative without replacing the source.
4. Stabilized MP4 — Prefer the verified stabilized output for playback.
5. Use Original File — Use the original when processing is skipped or fails.

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.

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

let playableURL = importedFile.stabilizedFileURL ?? importedFile.localFileURL

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 searches its bundle for the algorithm license. 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.