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.

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.

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 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.