{"id":48305908,"url":"https://github.com/gaelic-ghost/speakswiftlyserver","last_synced_at":"2026-05-11T03:27:46.063Z","repository":{"id":348839264,"uuid":"1200041620","full_name":"gaelic-ghost/SpeakSwiftlyServer","owner":"gaelic-ghost","description":"Local multi-client TTS server for macOS w/ universal profiles, custom text processing, \u0026 batch generation. HTTP w/ SSE and MCP. iOS Soon™","archived":false,"fork":false,"pushed_at":"2026-04-11T20:26:45.000Z","size":604,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T22:25:59.962Z","etag":null,"topics":["accessibility","hummingbird","localhost","macos","marvis","mcp","qwen3-tts","speakswiftly","swift","swift-package-manager","text-to-speech"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gaelic-ghost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-03T01:18:52.000Z","updated_at":"2026-04-11T20:26:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gaelic-ghost/SpeakSwiftlyServer","commit_stats":null,"previous_names":["gaelic-ghost/speakswiftlyserver"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/gaelic-ghost/SpeakSwiftlyServer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelic-ghost%2FSpeakSwiftlyServer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelic-ghost%2FSpeakSwiftlyServer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelic-ghost%2FSpeakSwiftlyServer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelic-ghost%2FSpeakSwiftlyServer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gaelic-ghost","download_url":"https://codeload.github.com/gaelic-ghost/SpeakSwiftlyServer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaelic-ghost%2FSpeakSwiftlyServer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31820369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","hummingbird","localhost","macos","marvis","mcp","qwen3-tts","speakswiftly","swift","swift-package-manager","text-to-speech"],"created_at":"2026-04-05T00:04:17.361Z","updated_at":"2026-05-02T16:01:42.229Z","avatar_url":"https://github.com/gaelic-ghost.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpeakSwiftlyServer\n\nStandalone Swift package for hosting the local `SpeakSwiftly` runtime behind an app-friendly HTTP API, an optional MCP surface, and a small embedded Apple-platform API.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Development](#development)\n- [Repo Structure](#repo-structure)\n- [Release Notes](#release-notes)\n- [License](#license)\n- [Embedding](#embedding)\n- [Configuration](#configuration)\n- [Codex Plugin](#codex-plugin)\n\n## Overview\n\n### Status\n\nThis project is actively available and stable enough to try.\n\n### What This Project Is\n\n`SpeakSwiftlyServer` is the standalone Swift Package Manager home for the local `SpeakSwiftly` server layer. It ships one reusable library target for embedding and one executable target, `SpeakSwiftlyServerTool`, for running the shared localhost service, LaunchAgent maintenance commands, and health checks.\n\nThe package exposes three user-facing surfaces:\n\n- a localhost HTTP API for app and operator control\n- an optional MCP surface for tool, resource, and prompt access\n- a small embedded Apple-platform API centered on the public `EmbeddedServer` observable model\n\n### Motivation\n\nThe goal is to give macOS and near-future Apple-platform apps one small, typed local speech-service layer without adding a second runtime stack or forcing every consumer to rebuild the same transport and lifecycle glue around `SpeakSwiftly`.\n\n## Quick Start\n\nBuild the package with Xcode's selected Swift toolchain:\n\n```bash\nxcrun swift build\n```\n\nRun the shared server executable locally:\n\n```bash\nxcrun swift run SpeakSwiftlyServerTool\n```\n\nCheck the current operator surface:\n\n```bash\nxcrun swift run SpeakSwiftlyServerTool help\nxcrun swift run SpeakSwiftlyServerTool healthcheck --base-url http://127.0.0.1:7338\n```\n\nFor contributor setup, validation, release workflow, and live end-to-end coverage, use [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Usage\n\nRun the server directly in the foreground:\n\n```bash\nxcrun swift run SpeakSwiftlyServerTool serve\n```\n\nInstall or refresh the per-user LaunchAgent with a config file:\n\nWhen the default staged tool path is used, this command first builds and stages the current checkout at `.release-artifacts/current/SpeakSwiftlyServerTool`, refreshes its bundled Metal resource, refreshes the staged ad-hoc signature, and then writes and bootstraps the LaunchAgent. Pass `--tool-executable-path /path/to/SpeakSwiftlyServerTool` only when you intentionally want to install a specific prebuilt executable instead.\n\n```bash\nxcrun swift run SpeakSwiftlyServerTool launch-agent install \\\n  --config-file ./server.yaml\n```\n\nUse the explicit promotion command when you want the lower-level \"build, stage, then reinstall\" spelling. This is mostly useful for release or operator scripts that want to name the promotion step directly; ordinary default-path refreshes can use `install`.\n\n```bash\nxcrun swift run SpeakSwiftlyServerTool launch-agent promote-live \\\n  --config-file ./server.yaml\n```\n\nInspect or remove the installed LaunchAgent:\n\n```bash\nxcrun swift run SpeakSwiftlyServerTool launch-agent status\nxcrun swift run SpeakSwiftlyServerTool launch-agent uninstall\n```\n\nThe package uses distinct default localhost ports by entrypoint:\n\n- direct executable startup defaults to `127.0.0.1:7338`\n- LaunchAgent installs default to `127.0.0.1:7337`\n- embedded app-owned sessions default to `127.0.0.1:7339`\n\nThe full transport contract lives in [API.md](./API.md).\n\n## Development\n\nThe contributor and maintainer workflow lives in [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nUse that guide for:\n\n- local setup and runtime expectations\n- validation commands\n- live end-to-end coverage\n- pull request and release workflow\n- monorepo and submodule handoff rules\n\nThe short version is:\n\n- use `xcrun swift test` for the normal package-development loop\n- use `sh scripts/repo-maintenance/validate-all.sh` for the full maintainer and CI gate\n- use `scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z --skip-version-bump` for the aligned release flow\n- use `scripts/repo-maintenance/config/profile.env` to confirm the active `swift-package` maintainer profile\n\n### Setup\n\nResolve package dependencies with the Xcode-selected Swift toolchain:\n\n```bash\nxcrun swift package resolve\n```\n\nInstall the local tools used by the full maintainer gate when you are running it outside CI:\n\n```bash\nbrew install swiftformat swiftlint\n```\n\n### Workflow\n\nUse a feature branch for normal repo work. Keep Swift package changes grounded in `Package.swift`, keep source and docs updates together when public behavior changes, and use [CONTRIBUTING.md](./CONTRIBUTING.md) for pull request, live-service, and monorepo handoff rules.\n\n### Validation\n\nRun the full local maintainer gate before handing off a complete change:\n\n```bash\nsh scripts/repo-maintenance/validate-all.sh\n```\n\nFor a narrower package-development loop, run:\n\n```bash\nxcrun swift build\nxcrun swift test\n```\n\n## Repo Structure\n\n```text\n.\n├── Sources/\n│   ├── SpeakSwiftlyServer/\n│   └── SpeakSwiftlyServerTool/\n├── Tests/\n├── docs/\n├── API.md\n├── CONTRIBUTING.md\n├── Package.swift\n└── README.md\n```\n\n- `Sources/SpeakSwiftlyServer/` contains the reusable library target.\n- `Sources/SpeakSwiftlyServerTool/` contains the unified executable wrapper.\n- `Tests/` contains unit, integration, and a small opt-in live E2E smoke suite.\n- `docs/` contains maintainer-facing supporting documentation.\n\n## Release Notes\n\nTagged release notes live in [GitHub Releases](https://github.com/gaelic-ghost/SpeakSwiftlyServer/releases) and the repo keeps matching historical release notes and release checklists under [docs/releases](./docs/releases/). Investigations and incident writeups live under [docs/investigations](./docs/investigations/).\n\n## License\n\nSee [LICENSE](./LICENSE).\n\n## Embedding\n\nThe supported public embedding surface is `EmbeddedServer`, defined in [Sources/SpeakSwiftlyServer/Host/ServerState.swift](./Sources/SpeakSwiftlyServer/Host/ServerState.swift). App code owns that one observable object directly, calls `liftoff()`, binds UI to its observable properties, and uses the same object for runtime controls, playback controls, voice-profile actions, and direct live speech submission through `queueLiveSpeech(...)`, including the shared `SpeakSwiftly.RequestContext` metadata model when one request needs caller-origin details.\n\n```swift\nimport SpeakSwiftlyServer\nimport SwiftUI\n\n@main\nstruct ExampleApp: App {\n    @State private var server = EmbeddedServer(\n        options: .init(\n            port: 7811,\n            runtimeProfileRootURL: FileManager.default\n                .urls(for: .applicationSupportDirectory, in: .userDomainMask)\n                .first?\n                .appendingPathComponent(\"ExampleApp/SpeakSwiftlyRuntime\", isDirectory: true)\n        )\n    )\n\n    var body: some Scene {\n        WindowGroup {\n            ContentView(server: server)\n                .task {\n                    try? await server.liftoff()\n                }\n        }\n    }\n}\n```\n\nIf you do not pass `EmbeddedServer.Options(port:)`, the embedded host defaults to `127.0.0.1:7339`. If you pass `EmbeddedServer.Options(runtimeProfileRootURL:)`, the server treats that as its profile-store root and bridges it at startup into the broader persistence root expected by the current pinned `SpeakSwiftly` runtime, while keeping the server's own runtime-configuration snapshot aligned with the same on-disk state.\n\n## Configuration\n\nThe shared server supports these environment variables:\n\n- `APP_CONFIG_FILE`\n- `APP_NAME`\n- `APP_ENVIRONMENT`\n- `APP_DEFAULT_VOICE_PROFILE_NAME`\n- `APP_HOST`\n- `APP_PORT`\n- `APP_SSE_HEARTBEAT_SECONDS`\n- `APP_COMPLETED_JOB_TTL_SECONDS`\n- `APP_COMPLETED_JOB_MAX_COUNT`\n- `APP_JOB_PRUNE_INTERVAL_SECONDS`\n- `APP_HTTP_ENABLED`\n- `APP_HTTP_HOST`\n- `APP_HTTP_PORT`\n- `APP_HTTP_SSE_HEARTBEAT_SECONDS`\n- `APP_MCP_ENABLED`\n- `APP_MCP_PATH`\n- `APP_MCP_SERVER_NAME`\n- `APP_MCP_TITLE`\n- `SPEAKSWIFTLY_PROFILE_ROOT`\n\nIf `APP_CONFIG_FILE` points at a YAML file, the server loads it through the package's Foundation URL-backed YAML provider and [swift-configuration](https://github.com/apple/swift-configuration), with environment variables taking precedence over YAML and YAML taking precedence over built-in defaults. Missing config files fail startup loudly. LaunchAgent install and refresh paths seed the default `~/Library/Application Support/SpeakSwiftlyServer/server.yaml` from the bundled template when that canonical file is missing.\n\n```yaml\napp:\n  name: speak-swiftly-server\n  environment: development\n  host: 127.0.0.1\n  port: 7338\n  sseHeartbeatSeconds: 10\n  completedJobTTLSeconds: 900\n  completedJobMaxCount: 200\n  jobPruneIntervalSeconds: 60\n  http:\n    enabled: true\n    host: 127.0.0.1\n    port: 7338\n    sseHeartbeatSeconds: 10\n  mcp:\n    enabled: false\n    path: /mcp\n    serverName: speak-swiftly-mcp\n    title: Speak Swiftly\n```\n\nThe app-managed install layout is centered on one per-user location under `~/Library/Application Support/SpeakSwiftlyServer`, with logs in `~/Library/Logs/SpeakSwiftlyServer`. The package exposes that layout directly through [AppManagedInstallLayout.swift](./Sources/SpeakSwiftlyServer/AppManagedInstallLayout.swift).\n\n## Codex Plugin\n\nThis repository is also packaged as a repo-local Codex plugin through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). The plugin points at the checked-in [`.mcp.json`](./.mcp.json) connection for the local `speak_swiftly` MCP server and the tracked [skills](./skills/) bundle that teaches Codex how to use the surface intentionally.\n\nThe plugin can be installed without using `socket` through Codex's Git-backed marketplace flow. The repo-local marketplace lives at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), and its single plugin entry points at this repository root with `source.path` set to `./` because the root directory is also the plugin root.\n\nPrefer the official Git-backed install and update path:\n\n```bash\ncodex plugin marketplace add gaelic-ghost/SpeakSwiftlyServer\ncodex plugin marketplace upgrade SpeakSwiftlyServer\n```\n\nAfter Codex adds or upgrades the marketplace, restart Codex, open the plugin directory in the Codex GUI, choose the `SpeakSwiftlyServer` marketplace, and install or enable `speak-swiftly-server` there. Manual local clone marketplaces and personal copied-payload entries are development, unpublished-testing, and fallback paths rather than the default user install story.\n\nThe [`socket`](https://github.com/gaelic-ghost/socket) repository is Gale's plugin superproject and marketplace catalog. Installing from the Git-backed socket marketplace is useful when you want SpeakSwiftlyServer plus Gale's other Codex plugins available from one marketplace:\n\n```bash\ncodex plugin marketplace add gaelic-ghost/socket\ncodex plugin marketplace upgrade socket\n```\n\nAfter adding `socket`, restart Codex, open the plugin directory in the Codex GUI, choose the `Socket` marketplace, and install or enable `speak-swiftly-server` plus any companion plugins you want. Use an explicit ref such as `gaelic-ghost/SpeakSwiftlyServer@vX.Y.Z` only when you want a pinned reproducible install rather than the release-aligned default branch.\n\nThe first plugin pass ships focused skills for:\n\n- broad MCP orientation\n- LaunchAgent setup and maintenance\n- runtime, playback, and queue control\n- voice workflows\n- text-profile workflows\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaelic-ghost%2Fspeakswiftlyserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaelic-ghost%2Fspeakswiftlyserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaelic-ghost%2Fspeakswiftlyserver/lists"}