Skip to content

Build OpenScreech from Source

This is a developer and contributor reference. It is not part of the normal first-use path for an installed OpenScreech application.

Prerequisites

  • macOS 14+
  • Xcode Command Line Tools (xcode-select --install)
  • Internet access on first build so SwiftPM can fetch dependencies

Full Xcode is only required for maintainers regenerating the app icon from its Icon Composer source. Ordinary app and DMG builds use the committed ICNS.

Build and Run From Terminal

cd OpenScreech-macOS
swift build
swift run OpenScreechApp

Build the HTTP Helper Directly

cd OpenScreech-macOS
swift run OpenScreechTranscriptionServer --port 8765 --token YOUR_TOKEN

Build a Double-Clickable .app

./OpenScreech-macOS/Packaging/Scripts/package-macos-app.sh
open OpenScreech-macOS/dist/OpenScreech.app

Optional: Install to /Applications

./OpenScreech-macOS/Packaging/Scripts/install-macos-app.sh

Optional: Build DMG

./OpenScreech-macOS/Packaging/Scripts/build_dmg.sh

Quick Tips

  • Test permissions using the same packaged .app you intend to run regularly. macOS can treat a SwiftPM executable and a packaged application as different permission clients.
  • Building the HTTP helper directly is useful for development, but the packaged app manages its own helper during ordinary use.

Visual Notes

  • TODO: add screenshot of dist/OpenScreech.app in Finder.
  • TODO: add screenshot of first app launch from Finder.