InstantEdit Video Tool

InstantEdit is a powerful GUI application designed to analyze and process video files, helping users identify and manage common issues such as short clips, exposure problems, shaky footage, and audio dead space. It also integrates with Google's Gemini AI for advanced video analysis.

---

Table of Contents

• User Installation (macOS)
• Development Setup
• GitHub Actions Setup (For Repository Maintainers)
• Google Cloud Setup (for Gemini Features)
• Additional Notes
• Google Cloud Credentials Setup for InstantEdit.video

---

User Installation (macOS)

These instructions are for installing the pre-built InstantEdit application on a macOS system.

Requirements:

• macOS 10.14 or later.

Option 1: PKG Installer (Recommended)

Installation Steps:

1. Download: Obtain the latest InstantEdit.pkg installer from the releases page.
2. Install: Double-click the InstantEdit.pkg file and follow the installation wizard.
   • You may be prompted for your administrator password
   • The app will be automatically installed to /Applications/InstantEdit.app
3. Launch: Find InstantEdit in your Applications folder or use Spotlight search (Cmd+Space, type "InstantEdit")

Note: The PKG installer includes all necessary dependencies and handles code signing/notarization automatically.

Additional Setup Required:

• For Gemini AI features you'll still need to complete the Google Cloud Setup section below.

---

Development Setup

These instructions are for developers who want to contribute to or modify the InstantEdit codebase.

Prerequisites

1. Install Homebrew dependencies:

   brew bundle --file Brewfile

2. Clone the Repository:

   # git clone <repository-url>
   # cd instantedit.video 

3. Create Python Virtual Environment: It's highly recommended to use a virtual environment.

   python3 -m venv venv

4. Activate Environment:

   source venv/bin/activate

   (To deactivate, simply run deactivate.)

5. Install Dependencies: Install the project in editable mode and then install all required packages:

   pip install --editable .
   pip install -r requirements.txt
   pip install pyinstaller

Building the macOS App

Option 1: Build App Only

# Build the .app bundle (unsigned, for local testing)
chmod +x scripts/build_mac.sh
./scripts/build_mac.sh

Option 2: Build, Sign, and Notarize (For Distribution)

# Set required environment variables
export APPLE_ID="your-apple-id@example.com"
export AC_PASSWORD="your-app-specific-password"  # from appleid.apple.com
export APPLE_TEAM_ID="YOUR10CHARTEAMID"

# Build, sign, notarize, and create PKG installer
chmod +x scripts/build_and_notarize_mac.sh
./scripts/build_and_notarize_mac.sh

Requirements for signing/notarization:

• Apple Developer ID Application certificate (for app signing)
• Apple Developer ID Installer certificate (for PKG signing)
• App-specific password from https://appleid.apple.com/account/manage

Running the Local Build

GUI Mode (Normal)

# Run the built app normally
open dist/InstantEdit.app

Console Mode (For Development/Debugging)

# Run with console output visible
dist/InstantEdit.app/Contents/MacOS/InstantEdit

Background with Log Capture

# Run in background and capture logs to file
dist/InstantEdit.app/Contents/MacOS/InstantEdit 2>&1 | tee instantedit_logs.txt &

Monitor System Logs

# In one terminal, monitor logs:
log stream --predicate 'process == "InstantEdit"' --info

# Then launch the app via Spotlight or Finder

You should now be able to run using the rajphoto entry point from within your activated virtual environment.

---

Making a Release

Releases are automated using GitHub Actions and are triggered by pushing a new Git tag to the repository. You can monitor the progress of the workflow in the "Actions" tab of the GitHub repository. Once completed, the new release will be available on the "Releases" page.

---

GitHub Actions Setup (For Repository Maintainers)

The GitHub Actions workflow automatically builds, signs, and notarizes the macOS application for distribution. This section is only needed if you're setting up the CI/CD pipeline.

Required GitHub Secrets

The workflow requires these 8 secrets to be configured in your repository settings:

Apple Developer Certificates

Get these from Apple Developer Account:

1. DEV_CERT_P12 - Base64-encoded Developer ID Application certificate (.p12 file)

   • Used for signing the .app bundle
   • Export from Keychain Access as .p12, then: base64 -i certificate.p12 | pbcopy

2. DEV_CERT_PASS - Password for the Developer ID Application certificate

   • The password you set when exporting the .p12 file

3. DEV_INSTALLER_CERT_P12 - Base64-encoded Developer ID Installer certificate (.p12 file)

   • Used for signing the .pkg installer
   • Export from Keychain Access as .p12, then: base64 -i installer_cert.p12 | pbcopy

4. DEV_INSTALLER_CERT_PASS - Password for the Developer ID Installer certificate

   • The password you set when exporting the installer .p12 file

5. KEYCHAIN_PASS - Password for the temporary keychain (can be any secure password)

   • Used by GitHub Actions to create a temporary keychain for certificates

Apple ID and Notarization

Get these from Apple ID Account Management:

6. APPLE_ID - Your Apple ID email address

   • The email associated with your Apple Developer account

7. AC_PASSWORD - App-specific password for notarization

   • Create at https://appleid.apple.com/account/manage under "App-Specific Passwords"
   • NOT your regular Apple ID password

8. APPLE_TEAM_ID - Your 10-character Apple Developer Team ID

   • Find at https://developer.apple.com/account#MembershipDetailsCard
   • Also visible in your certificate details

Setup Instructions

1. Get Apple Developer ID certificates:

   • Log into https://developer.apple.com/account/resources/certificates/
   • Create "Developer ID Application" certificate (for app signing)
   • Create "Developer ID Installer" certificate (for PKG signing)
   • Download and install both certificates in Keychain Access

2. Export certificates as .p12 files:

   • Open Keychain Access
   • Find your "Developer ID Application" certificate
   • Right-click → Export → Save as .p12 with a password
   • Repeat for "Developer ID Installer" certificate

3. Convert .p12 files to base64:

   base64 -i dev_id_application.p12 | pbcopy
   # Paste into DEV_CERT_P12 secret
   base64 -i dev_id_installer.p12 | pbcopy  
   # Paste into DEV_INSTALLER_CERT_P12 secret

4. Create app-specific password:

   • Go to https://appleid.apple.com/account/manage
   • Sign in with your Apple ID
   • Go to "App-Specific Passwords" section
   • Generate a new password for "GitHub Actions Notarization"
   • Copy the generated password to AC_PASSWORD secret

5. Add all secrets to your GitHub repository:

   • Go to your repo → Settings → Secrets and variables → Actions
   • Add each secret listed above

Workflow Output

The GitHub Actions workflow produces:

• dist/InstantEdit.pkg - Signed and notarized PKG installer
• GitHub Release with PKG installer attached

The resulting PKG can be distributed to users and will install without security warnings.

---

Google Cloud Setup (for Gemini Features)

Note: The packaged InstantEdit.pkg installer comes with Google Cloud credentials pre-configured for most users. You only need to follow these steps if you're:

• Setting up for development
• Building the app yourself
• Experiencing authentication issues

For Developers and App Builders

For complete setup instructions including service account creation and credential management, see: GOOGLE_CREDENTIALS_SETUP.md

Quick Setup (Development Only)

If you're developing the application:

1. Install Google Cloud SDK: Ensure you have the gcloud CLI installed.

2. Login for Application Default Credentials (ADC):

   gcloud auth application-default login

   Follow the prompts to authenticate with your Google account.

3. Set Quota Project: The application needs a project ID for billing and API quotas.

   • You can find your project ID by listing your available projects: gcloud projects list
   • Alternatively, find it in the Google Cloud Console.
   • Run the following command, replacing <your-project-id> with your actual Google Cloud project ID (the project used by this application is videoprocessing-456318, but you might use your own for development/testing):

     gcloud auth application-default set-quota-project <your-project-id>

     For example:

     gcloud auth application-default set-quota-project videoprocessing-456318

   This ensures that Google Cloud client libraries can correctly handle billing and quotas.

---

Additional Notes

InstantEdit is a comprehensive video analysis and processing application with an intuitive graphical user interface. All video processing features are accessible through the GUI, including:

• Video duration analysis and filtering
• Exposure detection (high/low exposure issues)
• Shaky footage detection and removal
• Audio analysis (speech, music, dead space detection)
• Music overlay capabilities
• Gemini AI-powered video analysis

The application automatically handles file management and provides visual feedback during processing operations.

Google Cloud Credentials Setup for InstantEdit.video

This guide explains how to set up Google Cloud credentials so that the packaged InstantEdit.video application can access Google Cloud services without requiring users to install gcloud CLI or authenticate manually.

Overview

The InstantEdit.video application uses two Google Cloud services:

• Google Cloud Storage: For uploading videos to be analyzed
• Vertex AI (Gemini): For AI-powered video analysis

Instead of requiring users to run gcloud auth application-default login, the application can be packaged with service account credentials.

Prerequisites

• Access to Google Cloud Console
• Project ID: videoprocessing-456318 (or your own project)
• Billing enabled on the project
• Required APIs enabled:
  • Vertex AI API
  • Cloud Storage API

Step-by-Step Setup

1. Create Service Account

Via Google Cloud Console:

1. Go to Google Cloud Console
2. Select your project videoprocessing-456318
3. Navigate to IAM & Admin → Service Accounts
4. Click Create Service Account
5. Fill in the details:
   • Service account name: instantedit-app-service
   • Service account ID: instantedit-app-service
   • Description: Service account for InstantEdit app
6. Click Create and Continue

Via gcloud CLI:

gcloud iam service-accounts create instantedit-app-service \
  --description="Service account for InstantEdit app" \
  --display-name="InstantEdit App Service Account" \
  --project=videoprocessing-456318

2. Grant Required Permissions

The service account needs these IAM roles:

Via Google Cloud Console:

1. In the Service Accounts page, find your new service account
2. Click on the service account email
3. Go to Permissions tab
4. Add the following roles:
   • Vertex AI User (roles/aiplatform.user)
   • Storage Object Admin (roles/storage.objectAdmin)
   • Vertex AI Service Agent (roles/aiplatform.serviceAgent)

Via gcloud CLI:

# Get the service account email
SERVICE_ACCOUNT="instantedit-app-service@videoprocessing-456318.iam.gserviceaccount.com"

# Grant Vertex AI User role (for Gemini)
gcloud projects add-iam-policy-binding videoprocessing-456318 \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/aiplatform.user"

# Grant Storage Object Admin role (for GCS bucket)
gcloud projects add-iam-policy-binding videoprocessing-456318 \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/storage.objectAdmin"

# Grant Vertex AI Service Agent role (additional for Gemini)
gcloud projects add-iam-policy-binding videoprocessing-456318 \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/aiplatform.serviceAgent"

3. Create Service Account Key

Via Google Cloud Console:

1. In the Service Accounts page, find your service account
2. Click on the service account email
3. Go to Keys tab
4. Click Add Key → Create new key
5. Select JSON format
6. Click Create
7. Save the downloaded file as google-credentials.json

Via gcloud CLI:

gcloud iam service-accounts keys create google-credentials.json \
  --iam-account=instantedit-app-service@videoprocessing-456318.iam.gserviceaccount.com \
  --project=videoprocessing-456318

4. For Development

1. Place the google-credentials.json file in your project root directory
2. The application will automatically detect and use it
3. Never commit this file to version control (it's already in .gitignore)

5. For Building the Packaged App

1. Place the google-credentials.json file in your project root directory
2. Run the build script: ./scripts/build_and_notarize_mac.sh
3. The credentials will be bundled into the app automatically

6. For GitHub Actions (CI/CD)

1. Go to your GitHub repository
2. Navigate to Settings → Secrets and variables → Actions
3. Add a new repository secret:
   • Name: GOOGLE_CREDENTIALS_JSON
   • Value: Copy the entire contents of your google-credentials.json file
4. The GitHub Actions workflow will automatically include the credentials in builds

Verification

To verify the credentials are working:

1. Development: Run the application locally - it should connect to Gemini without errors
2. Packaged App: The app should start without showing Google Cloud authentication errors
3. Check Logs: Look for log messages indicating successful Google Cloud client initialization

Security Considerations

Best Practices:

• ✅ Use service accounts instead of user credentials for production
• ✅ Grant least privilege (only necessary roles)
• ✅ Keep credentials file secure and never commit to version control
• ✅ Rotate service account keys regularly
• ✅ Monitor service account usage in Google Cloud Console

What the Service Account Can Do:

• Upload videos to the specific GCS bucket (videoprocessing-456446)
• Analyze videos using Vertex AI (Gemini models)
• Access only the resources needed for the application

What the Service Account Cannot Do:

• Access other Google Cloud projects
• Modify billing settings
• Create or delete resources
• Access user data outside the application scope

Troubleshooting

Common Issues:

1. "Google Cloud credentials are not properly configured"

   • Check that google-credentials.json exists in the right location
   • Verify the JSON file format is valid
   • Ensure the file is not empty

2. "Unable to connect to Google Cloud services"

   • Check internet connection
   • Verify the service account has the required permissions
   • Confirm the project ID and bucket name are correct

3. "Permission denied" errors

   • Verify the service account has the required IAM roles
   • Check that the APIs are enabled in the project

Debugging Steps:

1. Check credentials file location:

   # For development
   ls -la google-credentials.json
   
   # For packaged app, check logs for credential path

2. Verify service account permissions:

   gcloud projects get-iam-policy videoprocessing-456318 \
     --flatten="bindings[].members" \
     --format="table(bindings.role)" \
     --filter="bindings.members:instantedit-app-service@videoprocessing-456318.iam.gserviceaccount.com"

3. Test credentials manually:

   export GOOGLE_APPLICATION_CREDENTIALS="google-credentials.json"
   gcloud auth application-default print-access-token

File Structure

After setup, your project should have:

instantedit.video/
├── google-credentials.json          # Service account key (NOT in git)
├── google-credentials.json.template  # Template file (in git)
├── src/utils/auth.py                # Authentication utilities
├── .gitignore                       # Excludes credentials file
└── ...

Migration from User Credentials

If you previously used gcloud auth application-default login:

1. The new service account approach will take precedence
2. Users no longer need to install gcloud CLI
3. The app will work immediately after installation
4. No manual authentication steps required

Cost Considerations

• Service accounts are free
• You only pay for actual API usage (Vertex AI calls, Storage operations)
• Monitor usage in Google Cloud Console to track costs
• Set up billing alerts if needed

Maintenance

• Rotate keys: Generate new service account keys periodically
• Monitor usage: Check Google Cloud Console for unexpected activity
• Update permissions: Adjust IAM roles if application requirements change
• Backup credentials: Store credentials securely (not in version control)