How to Integrate Clypra's Capacitor Mobile Bridge for iOS and Android Deployment

Clypra's Capacitor mobile bridge connects the platform-agnostic core video editor to native iOS and Android capabilities through the CapacitorPlatformAdapter, enabling filesystem access, native encoding, and app store deployment while sharing the same codebase as the desktop Tauri build.

Clypra is an open-source video editing application built by AIEraDev with a platform-adapter architecture that isolates core editing logic from the host environment. When you integrate Clypra's Capacitor mobile bridge, you enable the same web-based interface to access native mobile capabilities like the filesystem, media codecs, and hardware-accelerated encoding on iOS and Android devices.

Prerequisites

Before configuring the mobile bridge, install the Capacitor CLI and core runtime from the repository root:

npm install @capacitor/core @capacitor/cli
npx cap init
npx cap add ios
npx cap add android

Configure the Capacitor Mobile Bridge

The entry point for mobile configuration is capacitor.config.ts in the repository root. This file defines the app ID, display name, and web asset directory (dist), along with optional live-reload settings for development.

When CAPACITOR_LIVE_RELOAD is enabled in your environment, the configuration points to a local development server:

const isLiveReload = process.env.CAPACITOR_LIVE_RELOAD === 'true';

const config = {
  appId: 'com.aiera.clypra',
  appName: 'Clypra',
  webDir: 'dist',
  server: isLiveReload
    ? {
        androidScheme: 'https',
        url: 'http://192.168.1.100:1420',
        cleartext: true,
      }
    : undefined,
};

Implement Platform Detection with CapacitorPlatformAdapter

Clypra uses a platform abstraction layer to detect whether it is running in a Capacitor environment. The CapacitorPlatformAdapter in src/core/platform/adapters/capacitorAdapter.ts implements the PlatformInterface and handles file URL conversion via Capacitor.convertFileSrc, routing storage to the Capacitor Filesystem API with graceful fallback to localStorage.

To detect mobile platforms in your code, import the platform detector from src/core/platform/index.ts:

import { Platform } from '@/core/platform';

if (Platform.isCapacitor()) {
  // Enable mobile-specific features like native sharing
  showNativeShareButton();
}

The isCapacitor() method delegates to the adapter's environment detection logic, ensuring your conditional code only executes in the mobile context.

Handle Mobile Video Export

When exporting video on mobile devices, Clypra routes through src/lib/export/mobileExport.ts and src/lib/export/mobileExportEncoder.ts. These modules select the appropriate encoder (H.264 / AAC) and invoke native file-save dialogs via Capacitor's Filesystem and Share plugins.

The generic export entry point in src/lib/export/videoExport.ts detects the platform and delegates to the mobile implementation when running under Capacitor:

import { exportVideo } from '@/lib/export/videoExport';
import { isCapacitor } from '@/core/platform';

async function handleExport() {
  const blob = await exportVideo(/* parameters */);
  
  if (isCapacitor()) {
    // Write to device storage using Capacitor Filesystem
    await window.Capacitor.Plugins.Filesystem.writeFile({
      path: `clypra-${Date.now()}.mp4`,
      data: await blob.arrayBuffer(),
      directory: 'Documents',
    });
    
    // Invoke native share dialog
    await window.Capacitor.Plugins.Share.share({
      files: ['file://path/to/export.mp4'],
      title: 'My Clypra Export',
    });
  } else {
    // Desktop fallback
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'clypra.mp4';
    a.click();
  }
}

Set Up Live Reload for Development

Enable rapid iteration by setting CAPACITOR_LIVE_RELOAD=true before running your development server. This configuration in capacitor.config.ts allows the Capacitor wrapper to load assets from your local Vite development server at http://<local-ip>:1420 without rebuilding the native project each time.

Run the development server with:

npm run dev

Then deploy to your connected device or emulator. Changes to the web source reflect immediately while preserving access to native APIs.

Build and Deploy to iOS and Android

Once configured, open the native projects in their respective IDEs to build and sign the applications:

npx cap open ios     # Opens Xcode

npx cap open android # Opens Android Studio

From Xcode or Android Studio, configure signing certificates, app icons, and permissions before building release binaries for distribution through the App Store or Google Play.

Summary

• Platform Isolation: Clypra's architecture separates core logic from host environments via the PlatformInterface in src/core/platform, allowing seamless integration of mobile-specific capabilities.
• Capacitor Configuration: The capacitor.config.ts file centralizes app metadata and development settings, including live-reload configuration for rapid testing.
• Adapter Pattern: CapacitorPlatformAdapter in src/core/platform/adapters/capacitorAdapter.ts bridges web APIs to native iOS/Android functionality, handling file URL conversion and storage routing.
• Mobile Export Pipeline: Video exports on mobile use mobileExport.ts and mobileExportEncoder.ts to leverage native encoders and filesystem access through Capacitor plugins.
• Unified Codebase: The same TypeScript codebase powers both desktop (Tauri) and mobile (Capacitor) deployments, with platform detection handled transparently.

Frequently Asked Questions

How does Clypra detect whether it is running in a Capacitor environment?

Clypra detects the Capacitor runtime through the isCapacitor() method exposed in src/core/platform/index.ts. This function delegates to the CapacitorPlatformAdapter, which checks for the presence of the Capacitor global object and native bridge availability, returning a boolean that triggers mobile-specific code paths.

What video encoders does Clypra use for mobile exports?

According to the source code in src/lib/export/mobileExportEncoder.ts, Clypra selects H.264 for video and AAC for audio when running on mobile devices. These hardware-accelerated codecs ensure efficient encoding on iOS and Android while maintaining compatibility with standard playback devices.

Can I use the same export code for desktop and mobile deployments?

Yes. The videoExport.ts module in src/lib/export/ serves as a platform-agnostic entry point that automatically delegates to mobileExport.ts when isCapacitor() returns true, or falls back to desktop-specific exporters for Tauri builds. This abstraction allows you to call exportVideo() without worrying about the underlying platform.

Where does Clypra store exported videos on mobile devices?

When running under Capacitor, Clypra writes exported videos to the device's Documents directory using the Capacitor Filesystem plugin, as implemented in src/lib/export/mobileExport.ts. The path is constructed using the app's sandboxed storage area, and files can be accessed later through the native share dialog or file manager.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}