feat: Add video quality parameter

[buhleryesco]

What

• This PR adds native support for the videoQuality parameter in the CameraPreview plugin for both iOS and Android.
• iOS: Implemented a priority-based switch that maps low, medium, and high to native presets while respecting aspectRatio.
• Android: Implements QualitySelector within CameraX, mapping the same levels to SD, HD, and FHD
• Stability: Integrated canSetSessionPreset checks on iOS to ensure hardware compatibility before applying settings.

Why

Problem: Default "High" quality videos were exceeding 10MB+, leading to frequent sync failures on low-bandwidth LTE.
Use cases for apps that are used with poor signal and need to be able to sync smaller quality photos/videos.

How

• iOS Implementation: Updated configureSessionPreset to use a tiered selection logic:

  • Low: Attempts .vga640x480 (Standard Definition).
  • Medium: Attempts .hd1280x720 (720p HD).
  • High: Uses a nested switch based on aspectRatio. If 16:9 is requested, it tries .hd1920x1080 or .hd4K3840x2160. For other ratios, it defaults to .photo to maximize sensor resolution.

• Android Implementation: Utilized CameraX's QualitySelector with a tiered selection logic.

  • Low: tries to map to SD or lower. Uses FallbackStrategy.lowerQualityOrHigherThan
  • Medium: attempts HD or lower. Uses FallbackStrategy.lowerQualityOrHigherThan
  • High attempts FHD with FallbackStrategy.higherQualityOrLowerThan

• All "high" quality (the default) uses the existing logic prior to the PR

Testing

Verified file sizes and resolutions using native logs and JS-side file inspection for Android and iOS.

Not Tested

• Non samsung phones.
• Low level quality in low light settings.

Summary by CodeRabbit

• New Features

  • Added configurable video quality setting for camera preview with three options: 'low', 'medium', and 'high' (default: 'high')
  • Users can now adjust video recording quality on both iOS and Android platforms

• Documentation

  • Updated documentation with video quality configuration details

[coderabbitai]

📝 Walkthrough

Walkthrough

A new videoQuality option ('low', 'medium', 'high') is added to the camera preview plugin API, enabling users to control video capture quality. The setting is propagated from TypeScript definitions through Android and iOS platform implementations into camera session configurations and preset selection logic.

Changes

Cohort / File(s)	Summary
Documentation & Type Definitions README.md, src/definitions.ts	Added VideoQuality type alias and videoQuality optional property to CameraPreviewOptions with platform-specific notes; updated documentation formatting.
Android Core Configuration android/src/main/java/app/capgo/capacitor/camera/preview/model/CameraSessionConfiguration.java	Extended constructor to accept videoQuality parameter; added private field and public getter getVideoQuality() with "high" default fallback.
Android Implementation android/src/main/java/app/capgo/capacitor/camera/preview/CameraPreview.java	Extracts videoQuality from plugin call parameters and passes it to CameraSessionConfiguration constructor.
Android Video Capture android/src/main/java/app/capgo/capacitor/camera/preview/CameraXView.java	Implements quality-driven QualitySelector logic ("low"→SD/LOWEST, "medium"→HD/SD, "high"→FHD/HD/SD); propagates videoQuality through CameraSessionConfiguration constructor calls across multiple camera operation pathways (switchToDevice, flipCamera, setAspectRatio, setPreviewSize, setGridMode, etc.).
iOS Camera Session ios/Sources/CapgoCameraPreviewPlugin/CameraController.swift	Adds videoQuality state property (default "high"); updates prepare() and bestPreset() signatures to accept videoQuality; implements quality-based preset selection logic before aspect ratio branching.
iOS Plugin Interface ios/Sources/CapgoCameraPreviewPlugin/Plugin.swift	Extracts videoQuality from start call parameters (default "high") and forwards it to cameraController.prepare().

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Plugin
    participant CameraController as Platform<br/>(Camera/Controller)
    participant SessionConfig as Session Config
    participant Camera as Camera Engine

    Client->>Plugin: startCamera({videoQuality: 'high'})
    Plugin->>CameraController: prepare(..., videoQuality: 'high')
    CameraController->>SessionConfig: new CameraSessionConfiguration(..., videoQuality)
    SessionConfig->>SessionConfig: store videoQuality
    CameraController->>CameraController: selectPreset(quality: 'high')
    CameraController->>Camera: configure(presets, quality)
    Camera->>Camera: set video capture quality
    Camera-->>Client: camera ready

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: add option to disable focus indicator #214: Shares the pattern of extending CameraSessionConfiguration's constructor signature and propagating new session parameters through platform-specific call sites.

Poem

🐰 A whisker-tweaking quality quest,
From low to high, we've done our best!
Presets now dance to video's tune,
Your camera sings a sharper song—
Quality flows where it belongs! 📹✨

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding a video quality parameter to the CameraPreview plugin.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

ios/Sources/CapgoCameraPreviewPlugin/Plugin.swift (1)

756-757: Invalid videoQuality values fall back silently to .photo or .high.

While TypeScript types provide compile-time safety, the native layer lacks explicit validation. If a caller bypasses TypeScript with an invalid value (e.g., "hgh"), configureSessionPreset will match the default case and silently fall back to .photo or .high depending on device capability. This is safe and prevents crashes, but invalid inputs go unnoticed. Consider adding a warning log for unrecognized values to improve observability.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}