Codakey
Play
← Back to openscreen

How to Deploy & Use openscreen

OpenScreen Deployment and Usage Guide

1. Prerequisites

Development Environment:

  • Node.js 18+ (for building from source)
  • npm or yarn package manager
  • Git

Operating System Permissions:

  • macOS: Full Disk Access for Terminal (to bypass Gatekeeper) and Screen Recording/Accessibility permissions
  • Linux: Screen recording permissions for your desktop environment (varies by distro)
  • Windows: No special permissions beyond standard screen recording access

Hardware:

  • Modern CPU with hardware video encoding support (recommended)
  • Sufficient RAM for video processing (minimum 4GB, 8GB+ recommended)

2. Installation

Option A: Download Pre-built Binaries (Recommended for End Users)

  1. Visit the GitHub Releases page
  2. Download the appropriate installer for your platform:
    • macOS: .dmg file
    • Linux: .AppImage file
    • Windows: .exe file

Option B: Build from Source (For Developers/Contributors)

  1. Clone the repository:

    git clone https://github.com/siddharthvaddem/openscreen.git
cd openscreen

  2. Install dependencies:

    npm install
# or
yarn install

3. Configuration

Environment Setup

No API keys or external services required. OpenScreen is entirely local and offline.

Important Build Dependencies:

  • Electron 25+ (handled by npm dependencies)
  • WebAssembly support for web-demuxer (included in build)
  • PixiJS for canvas rendering (included)

Project Structure Key Files:

  • src/lib/exporter/frameRenderer.ts - Handles frame composition with effects
  • src/lib/exporter/videoExporter.ts - Main video export pipeline
  • src/lib/exporter/streamingDecoder.ts - Video decoding using WebDemuxer
  • src/lib/exporter/gifExporter.ts - GIF export functionality
  • src/lib/exporter/annotationRenderer.ts - Annotation rendering system

4. Build & Run

Development Mode

  1. Start the development server:

    npm run dev
# or
yarn dev

  2. The app will open in Electron with hot-reload enabled for React components.

Production Build

  1. Build the application:

    npm run build
# or
yarn build

  2. Package for your platform:

    # For current platform
npm run dist

# For specific platforms
npm run dist:mac
npm run dist:linux
npm run dist:win

  3. Find the packaged application in the dist folder.

macOS Specific Setup (After Installation)

If Gatekeeper blocks the app:

  1. Open Terminal

  2. Run the bypass command:

    xattr -rd com.apple.quarantine /Applications/Openscreen.app

  3. Grant necessary permissions:

    • Go to System Settings > Privacy & Security
    • Grant "Screen Recording" permission
    • Grant "Accessibility" permission

Linux Specific Setup

  1. Make the AppImage executable:

    chmod +x Openscreen-Linux-*.AppImage

  2. Run the application:

    ./Openscreen-Linux-*.AppImage

  3. If you encounter sandbox errors:

    ./Openscreen-Linux-*.AppImage --no-sandbox

5. Deployment

For End Users

  • macOS: Distribute via .dmg files (consider notarization for better Gatekeeper compatibility)
  • Linux: Use .AppImage for universal compatibility across distributions
  • Windows: Use .exe installer with proper code signing (recommended)

Distribution Platforms

  1. GitHub Releases: Primary distribution channel
  2. Homebrew (for macOS): Consider creating a cask for easier installation
  3. Snap/Flatpak (for Linux): Package for Linux app stores
  4. Microsoft Store (for Windows): For wider Windows distribution

Self-Hosting Considerations

Since OpenScreen is a desktop Electron application, traditional web hosting doesn't apply. However:

  1. Update Server: Consider implementing an auto-update mechanism using:

    • Electron's autoUpdater module
    • GitHub Releases as update source
    • S3 or similar for hosting update files

  2. Asset Hosting: Background wallpapers and templates can be hosted on CDN for in-app downloads

6. Troubleshooting

Common Issues and Solutions

Issue: App crashes on launch

  • Solution: Check console logs with npm run dev to identify the error
  • macOS: Ensure all permissions are granted in System Settings
  • Linux: Try running with --no-sandbox flag

Issue: Screen recording not working

  • macOS:
    1. Ensure Terminal has Full Disk Access
    2. Grant Screen Recording permission to OpenScreen
    3. Restart the app after granting permissions
  • Linux:
    1. Check your desktop environment's screen recording settings
    2. For GNOME: Enable screen recording in Settings > Privacy
    3. For KDE: Check system permissions

Issue: Video export fails or is slow

  • Solution:
    1. Ensure hardware encoding is supported (check VideoEncoder.isConfigSupported)
    2. Reduce export resolution if hardware encoding fails
    3. Close other memory-intensive applications during export

Issue: GIF export quality issues

  • Solution:
    1. Adjust frame rate in GIF export settings (lower = smaller file)
    2. Use appropriate size presets from GIF_SIZE_PRESETS
    3. Consider reducing motion in source video for better GIF compression

Issue: Annotations not rendering correctly

  • Solution: Check annotationRenderer.ts for SVG path parsing issues
  • Ensure scale factors are correctly applied to annotation coordinates

Issue: "WASM not loaded" error

  • Solution:
    1. Clear npm cache: npm cache clean --force
    2. Reinstall dependencies: rm -rf node_modules && npm install
    3. Ensure web-demuxer.wasm is correctly copied to build output

Issue: Build fails on Linux

  • Solution: Install required system dependencies: 
    # Ubuntu/Debian
sudo apt-get install build-essential libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2

# Fedora
sudo dnf install @development-tools libX11-devel libXrandr-devel libXcursor-devel libXinerama-devel libXi-devel libXext-devel

Debugging Tips

  1. Enable Developer Tools: In the app, use Ctrl+Shift+I (or Cmd+Option+I on macOS) to open dev tools
  2. Check Console Logs: Look for errors in the console tab
  3. Verify Dependencies: Ensure all npm packages are correctly installed with npm list --depth=0
  4. Clear Cache: Delete node_modules and package-lock.json, then reinstall if experiencing weird issues

Performance Optimization

  1. For Large Videos:

    • Use trim regions to export only needed sections
    • Reduce zoom complexity if experiencing frame drops
    • Export at lower resolution for faster processing

  2. Memory Issues:

    • The MAX_ENCODE_QUEUE in videoExporter.ts is set to 120 for hardware encoding throughput
    • Reduce this value if experiencing memory issues on low-RAM systems
    • Monitor memory usage during export in dev tools

Getting Help

  1. Check existing GitHub Issues
  2. Review the project roadmap for known limitations
  3. Ask questions using the DeepWiki badge in the README

Note: This is a beta project. Some features may be unstable. Always test exports before using for critical work.

← Project overviewView alternatives to openscreen →