SpeakSwiftlyServer

Swift executable package for a shared localhost host process that exposes the public SpeakSwiftly runtime surface through an app-friendly HTTP API and an optional MCP surface.

Table of Contents

• Overview
• Setup
• Usage
• Embedding
• Configuration
• Contributing
• Development
• Repository Layout
• Verification
• Roadmap
• License

Overview

This repository is the standalone Swift service for SpeakSwiftly. It uses Hummingbird to host one macOS process with job tracking, server-sent events, an operator-friendly HTTP API, and an optional MCP surface, while delegating speech, voice-profile management, and worker lifecycle to the typed SpeakSwiftly runtime.

Deployment Targets

Current deployment targets are:

• macOS 15 and newer for the standalone server package and initial app-managed installation path
• iOS 18 and newer for a near-future app-facing reuse path once the host logic is split cleanly enough to be consumed from an iOS app

Linux support is a medium-term consideration rather than a current promise. A separate Linux implementation in Rust is more likely.

Motivation

The goal is to give macOS apps one small, typed, app-managed service layer for local speech work without introducing a separate Python runtime or a second control model beside SpeakSwiftly.

The package stays intentionally narrow. Hummingbird owns transport hosting, SpeakSwiftly owns speech, profile, and runtime lifecycle behavior, TextForSpeech owns customizable text normalization, and the server keeps only the state it needs for retained snapshots, SSE replay, and MCP resources.

Current SpeakSwiftly Alignment

This server is aligned to the current public library surface of its resolved SpeakSwiftly 3.0.4 package dependency.

Today the server relies on the current typed runtime capabilities that matter for transport hosting:

• SpeakSwiftly.liftoff(configuration:)
• runtime.statusEvents()
• runtime.generate.speech(text:with:textProfileName:textContext:sourceFormat:)
• runtime.generate.audio(text:with:textProfileName:textContext:sourceFormat:)
• runtime.generate.batch(_:with:)
• runtime.voices.create(design:from:vibe:voice:outputPath:)
• runtime.voices.create(clone:from:vibe:transcript:)
• runtime.voices.list()
• runtime.voices.rename(_:to:)
• runtime.voices.reroll(_:)
• runtime.voices.delete(named:)
• runtime.jobs.generationQueue()
• runtime.jobs.list()
• runtime.jobs.job(id:)
• runtime.jobs.expire(id:)
• runtime.artifacts.files()
• runtime.artifacts.file(id:)
• runtime.artifacts.batches()
• runtime.artifacts.batch(id:)
• runtime.player.list()
• runtime.player.state()
• runtime.player.pause()
• runtime.player.resume()
• runtime.player.clearQueue()
• runtime.player.cancelRequest(_:)
• runtime.overview()
• runtime.status()
• runtime.switchSpeechBackend(to:)
• runtime.reloadModels()
• runtime.unloadModels()
• runtime.request(id:)
• runtime.updates(for:)

For text normalization, the server stays on the public TextForSpeech model surface through the runtime normalizer rather than inventing a parallel server-only schema:

• runtime.normalizer.profiles.active()
• runtime.normalizer.profiles.stored(id:)
• runtime.normalizer.profiles.list()
• runtime.normalizer.profiles.effective(id:)
• runtime.normalizer.persistence.load()
• runtime.normalizer.persistence.save()
• runtime.normalizer.profiles.create(id:name:replacements:)
• runtime.normalizer.profiles.store(_:)
• runtime.normalizer.profiles.use(_:)
• runtime.normalizer.profiles.delete(id:)
• runtime.normalizer.profiles.reset()
• runtime.normalizer.profiles.add(...)
• runtime.normalizer.profiles.replace(...)

... View full README on GitHub