hermes/blitztext-app-linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial open source preview

Browse Source
This commit is contained in:
cmagnussen 2026-05-21 14:16:04 +02:00
commit 4f59160f88
22 changed files with 848 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/CODEOWNERS vendored Normal file
View File

@ -0,0 +1 @@
* @cmagnussen

30
.github/ISSUE_TEMPLATE/bug_report.md vendored Normal file
View File

@ -0,0 +1,30 @@
---
name: Bug report
about: Report something broken in the macOS preview
title: ""
labels: bug
assignees: ""
---
## What happened?
## What did you expect?
## Steps to reproduce
1.
2.
3.
## Environment
- macOS version:
- Mac model/chip:
- Xcode version:
- Did this happen before or after entering an OpenAI API key?:
## Notes
Do not paste API keys, private recordings, confidential transcripts, or screenshots with sensitive content.

20
.github/ISSUE_TEMPLATE/feature_request.md vendored Normal file
View File

@ -0,0 +1,20 @@
---
name: Feature request
about: Suggest an idea for the preview
title: ""
labels: enhancement
assignees: ""
---
## What would you like?
## Why does it matter?
## Possible approach
## Privacy or security impact
Would this send data to a new service, store more local data, or change how API keys are handled?

19
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,19 @@
## What changed?
## Why?
## How did you test it?
## AI assistance
Did you use AI-assisted coding tools? If yes, briefly mention where.
## Checklist
- [ ] I ran `./build.sh --debug` or explained why not.
- [ ] I did not commit API keys, tokens, private recordings, or confidential transcripts.
- [ ] I considered whether this changes privacy, security, or data flow.
- [ ] I kept the change focused on the macOS preview scope.

7
.github/dependabot.yml vendored Normal file
View File

@ -0,0 +1,7 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly

32
.github/secret-scan-patterns.txt vendored Normal file
View File

@ -0,0 +1,32 @@
# Secret hygiene patterns used by .github/workflows/ci.yml.
# One extended-regex per line. Lines starting with `#` and blank lines are ignored.
# Keep this file out of the scan via --exclude in the workflow.
# OpenAI keys and config tokens
sk-[A-Za-z0-9_-]{20,}
OPENAI_API_KEY[[:space:]]*=
APP_SECRET[[:space:]]*=
# AWS access keys
AKIA[0-9A-Z]{16}
ASIA[0-9A-Z]{16}
# GitHub tokens
ghp_[A-Za-z0-9]{36}
ghs_[A-Za-z0-9]{36}
ghu_[A-Za-z0-9]{36}
gho_[A-Za-z0-9]{36}
github_pat_[A-Za-z0-9_]{20,}
# Slack tokens and webhooks
xox[abprs]-[A-Za-z0-9-]{10,}
hooks\.slack\.com/services/
# Discord webhooks
discord(app)?\.com/api/webhooks/
# Google API keys
AIza[0-9A-Za-z_-]{35}
# Generic private key blocks
-----BEGIN [A-Z ]*PRIVATE KEY-----

52
.github/workflows/ci.yml vendored Normal file
View File

@ -0,0 +1,52 @@
name: CI
on:
pull_request:
push:
branches:
- main
permissions:
contents: read
jobs:
build-macos:
name: Build macOS app
runs-on: macos-14
timeout-minutes: 30
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Secret hygiene scan
run: |
patterns_file=.github/secret-scan-patterns.txt
if [ ! -f "$patterns_file" ]; then
echo "Missing $patterns_file"
exit 1
fi
pattern="$(grep -vE '^[[:space:]]*(#|$)' "$patterns_file" | paste -sd'|' -)"
if [ -z "$pattern" ]; then
echo "No patterns loaded from $patterns_file"
exit 1
fi
if grep -RInE \
--exclude-dir=.git \
--exclude=secret-scan-patterns.txt \
"$pattern" .; then
echo "Potential secret or private project reference found."
exit 1
fi
- name: Select Xcode
run: sudo xcode-select -s /Applications/Xcode_16.2.app || sudo xcode-select -s /Applications/Xcode.app
- name: Install XcodeGen
run: |
if ! command -v xcodegen >/dev/null 2>&1; then
brew install xcodegen
fi
- name: Build
run: ./build.sh --debug

32
.gitignore vendored Normal file
View File

@ -0,0 +1,32 @@
# Xcode
*.xcuserstate
*.xcuserdatad/
xcuserdata/
*.xcodeproj/
DerivedData/
.derivedData*/
build/
*.xcarchive
*.dSYM
*.dSYM.zip
# macOS
.DS_Store
# Local app artifacts
Blitztext.app
dist/
models/
*.mlmodel
*.mlmodelc/
*.mlpackage/
# Secrets and local config
.env
.env.*
*.local
Secrets.swift
*.xcconfig
# Tooling
node_modules/

9
CODE_OF_CONDUCT.md Normal file
View File

@ -0,0 +1,9 @@
# Code Of Conduct
Be kind, direct, and constructive.
This is a small experimental project. Good discussion is welcome; personal attacks, harassment, or hostile behavior are not.
If a conversation gets heated, slow down and move back to the concrete technical question.
Maintainers may close, hide, or moderate issues, comments, and pull requests that make collaboration harder or unsafe.

50
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,50 @@
# Contributing
Thanks for taking a look at Blitztext macOS Preview.
This repository is intentionally a preview. Contributions should make it easier to learn from, build, fork, or safely extend.
## Good First Contributions
- improve build instructions
- fix confusing UI text
- improve error messages
- add tests around parsing or quality filters
- document local model experiments
- simplify setup
## Before Opening A Pull Request
Please include:
- what changed
- why it changed
- how you tested it
- whether you used AI-assisted coding tools
Keep changes small when possible. Avoid unrelated cleanup in the same PR.
## Local Build
```bash
./build.sh --debug
```
## Security And Privacy
- Never commit API keys, tokens, private audio, or confidential transcripts.
- Avoid adding telemetry, hosted services, or external dependencies without a clear issue first.
- Call out privacy-impacting changes in the pull request description.
- Keep the preview honest: do not describe remote OpenAI workflows as offline or local.
## Project Boundaries
This preview currently does not include:
- other platforms
- a hosted backend
- packaged releases
- bundled local model files
- local text rewriting
Those can be discussed in issues, but please keep PRs focused on the current macOS preview unless a maintainer agrees on a larger direction first.

21
LICENSE Normal file
View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Blitztext contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

146
README.md Normal file
View File

@ -0,0 +1,146 @@
# Blitztext App
Blitztext App is an experimental open-source macOS menubar app for turning speech into text.
It is intentionally small and unfinished. The goal is to make a real workflow visible and hackable: press a hotkey, speak, get text back, optionally rewrite it, and paste it into the app you were using.
This is a learning and experimentation project, not a polished product.
> Preview status: bring your own OpenAI API key, no hosted backend, no warranty, no support guarantee.
## What It Does
- **Blitztext**: record speech and transcribe it.
- **Blitztext+**: record speech, transcribe it, then turn the rough draft into cleaner writing.
- **Blitztext $%&!**: turn frustrated speech into a calmer message.
- **Blitztext :)**: add fitting emojis to dictated text.
## Important Preview Notes
- macOS only.
- Bring your own OpenAI API key.
- No hosted Blitztext backend is included or provided.
- In online mode, audio and text are sent directly from the app to the OpenAI API.
- Optional local transcription via WhisperKit/CoreML if you install a compatible model locally.
- `./build.sh` creates a locally ad-hoc-signed development app. No notarized release binary is provided.
- Not production ready.
- No warranty and no support guarantee.
You are welcome to use, fork, adapt, and share this project under the license terms.
The intent is not to ship a one-click finished app. The intent is to make a real AI workflow understandable: clone it, build it, read the code, change it, break it, fix it, and suggest improvements. If you only want to download something and never look inside, this preview will probably feel rough. If you want to learn how a small native macOS AI app is put together, you are in the right place.
## Screenshots
<table>
<tr>
<td><img src="docs/screenshots/online-mode.png" alt="Blitztext online transcription mode" width="420"></td>
<td><img src="docs/screenshots/local-mode.png" alt="Blitztext secure local transcription mode" width="420"></td>
</tr>
<tr>
<td><img src="docs/screenshots/local-model-picker.png" alt="Blitztext local model picker" width="420"></td>
<td><img src="docs/screenshots/settings-customize.png" alt="Blitztext settings and customization view" width="420"></td>
</tr>
</table>
## Requirements
- macOS 14 or newer
- Xcode 16 or newer (Swift 5.10), with Command Line Tools installed and selected for `xcodebuild`
- [XcodeGen](https://github.com/yonaskolb/XcodeGen) to generate the Xcode project
- For online transcription and rewriting: an OpenAI API key with access to:
- `whisper-1` for transcription
- `gpt-4o-mini` and optionally `gpt-4o` for rewriting
- For local-only transcription: a WhisperKit CoreML model in:
`~/Library/Application Support/Blitztext/models/whisperkit/`
The build also pulls one Swift Package dependency automatically:
- [`argmax-oss-swift`](https://github.com/argmaxinc/argmax-oss-swift) (WhisperKit) — used for local on-device transcription.
Install XcodeGen if needed:
```bash
brew install xcodegen
```
## Build And Run
```bash
git clone https://github.com/cmagnussen/blitztext-app.git
cd blitztext-app
./build.sh --run
```
For a local install into `/Applications`:
```bash
./build.sh --install --run
```
The generated `.app` is ad-hoc signed for local development only. Do not treat it as a trusted redistributable binary. A public binary release would need Developer ID signing and notarization.
On first launch, either paste your own OpenAI API key for online workflows or install a WhisperKit CoreML model for local transcription. Rewriting workflows still require OpenAI.
For fully local transcription, install a WhisperKit CoreML model and enable **Sicherer Lokaler Modus** in the app.
For a slower, more explicit walkthrough, see [docs/setup.md](docs/setup.md).
## Permissions
Blitztext asks for:
- **Microphone**: to record your voice.
- **Accessibility**: to paste the result back into the app you were using.
If you do not grant Accessibility permission, you can still copy results manually.
## Data Flow
The preview has no custom backend.
```text
Online transcription: Your Mac -> OpenAI Audio Transcriptions API
Text rewriting: Your Mac -> OpenAI Chat Completions API
Local transcription: Your Mac -> WhisperKit/CoreML on device
```
The app stores your OpenAI API key in the user's macOS Keychain.
Read [docs/privacy.md](docs/privacy.md) before using the preview with sensitive content.
## Project Structure
```text
BlitztextMac/
App/ App lifecycle and paste handling
Features/ Workflows, menu bar UI, settings
Services/ Recording, OpenAI calls, hotkeys, local storage
Views/ Shared SwiftUI views
build.sh Local build script
docs/ Setup, privacy, roadmap, preflight, landing page notes
```
## Local Models
Local transcription is available as an experimental WhisperKit/CoreML path. The app does not bundle a model; choose one in the app, click install, and then switch on **Sicherer Lokaler Modus** from the menu bar or settings.
See [docs/local-models.md](docs/local-models.md).
## Contributing
Contributions are welcome, especially if they make the preview easier to build, understand, or fork.
Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
## Support And Roadmap
This preview has no formal support promise. See [SUPPORT.md](SUPPORT.md) for how to ask for help without sharing secrets.
The current direction is documented in [ROADMAP.md](ROADMAP.md). Maintainer-facing release checks live in [docs/open-source-preflight.md](docs/open-source-preflight.md).
## License
Code is released under the MIT License. See [LICENSE](LICENSE).
Project names, logos, and app icons are not automatically granted as trademarks or brand assets. See [TRADEMARKS.md](TRADEMARKS.md).

31
ROADMAP.md Normal file
View File

@ -0,0 +1,31 @@
# Roadmap
This is a preview roadmap, not a promise.
## Current Scope
- macOS menubar app
- local recording and hotkeys
- direct OpenAI API calls with a user-provided API key
- transcription, rewriting, calmer-message, and emoji workflows
- no hosted backend
- no other platforms
- no packaged public release
## Next Useful Work
- Make first-run setup clearer.
- Improve credential setup, validation, and recovery UX.
- Add a small automated test layer around prompt construction and text quality filters.
- Add provider boundaries so OpenAI and future local transcription can be swapped more cleanly.
- Prototype local transcription with WhisperKit or whisper.cpp.
- Reduce the Accessibility blast radius, ideally by moving synthetic paste into a smaller helper with narrower responsibilities.
- Add stronger supply-chain checks around downloaded local speech models.
- Add signed and notarized release builds when the project is ready for non-developer users.
## Not In Scope Yet
- Production support.
- Accounts, sync, teams, or hosted infrastructure.
- Claims that the app is offline or privacy-complete.
- App Store distribution.

36
SECURITY.md Normal file
View File

@ -0,0 +1,36 @@
# Security Policy
Blitztext macOS Preview is experimental software.
It is provided as-is, without warranty, support guarantees, or production-readiness claims.
## Supported Versions
Only the current `main` branch is considered for security fixes.
## Reporting A Vulnerability
Please do not open a public issue with sensitive security details.
Use GitHub private vulnerability reporting for this repository. Maintainers should enable it before making the repository public.
If private vulnerability reporting is not available yet, open a minimal public issue titled `Security contact request` without technical details.
Do not include OpenAI API keys, access tokens, private recordings, or confidential transcripts in a report.
Include:
- what you found
- how to reproduce it
- what data or system access could be affected
- your suggested fix, if you have one
## Security Notes
- The app sends audio and text directly to OpenAI when you use the remote workflows.
- Your OpenAI API key is stored in the user's macOS Keychain.
- Temporary audio files may exist briefly during processing.
- Accessibility permission allows the app to paste text into the current app.
- The app currently runs **without** the macOS App Sandbox. This is a deliberate trade-off for the preview: the menubar workflow needs Accessibility-based paste into arbitrary frontmost apps, system-wide hotkeys, and Application Support paths for local WhisperKit models, all of which are awkward or impossible inside a strict sandbox. Hardened Runtime is enabled, and the entitlements are limited to microphone input and outbound network access. Reintroducing the sandbox is on the roadmap once these flows are reworked.
Do not use this preview for confidential or regulated data without your own review.

25
SUPPORT.md Normal file
View File

@ -0,0 +1,25 @@
# Support
Blitztext App is an experimental preview. There is no service-level agreement, paid support channel, or guarantee that issues will be fixed.
## Before Asking For Help
- Make sure you can build the app with `./build.sh --debug`.
- Check that your OpenAI API key is entered in the app settings.
- Confirm that macOS microphone permission is granted.
- Grant Accessibility permission if you expect automatic paste into other apps.
- Read [docs/privacy.md](docs/privacy.md) before testing with sensitive content.
## Where To Ask
Use GitHub Issues for reproducible bugs and focused feature ideas.
Please do not post:
- OpenAI API keys
- access tokens
- private audio recordings
- confidential transcripts
- screenshots that show sensitive content
For security-sensitive reports, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.

7
TRADEMARKS.md Normal file
View File

@ -0,0 +1,7 @@
# Trademarks And Branding
The source code in this repository is licensed under the MIT License.
The project name, app name, logos, icons, and visual identity are not granted as trademarks or brand assets by the MIT License.
You may fork the code under the license terms. If you publish a fork as a separate app or service, use your own name, icon, and branding unless you have explicit permission.

33
docs/github-settings.md Normal file
View File

@ -0,0 +1,33 @@
# GitHub Settings Checklist
These settings are not stored in the repository. Configure them in GitHub before going public.
## Security
- Enable Dependabot alerts.
- Enable secret scanning.
- Enable push protection for supported secret types.
- Enable private vulnerability reporting when available.
## Branch Protection
Protect `main`:
- require pull request before merge
- require at least one approval
- require the CI workflow to pass
- dismiss stale approvals when new commits are pushed
- block force pushes
## Actions
- Keep default workflow permissions read-only.
- Require approval for workflows from first-time contributors.
- Do not add repository secrets unless they are truly needed.
## Community
- Keep Issues enabled for bugs and focused requests.
- Enable Discussions only if you want a lower-friction place for questions.
- Set repository topics after the project is public.
- Review the GitHub community profile before sharing the repo widely.

82
docs/landing-page-brief.md Normal file
View File

@ -0,0 +1,82 @@
# Landing Page Brief
Domain: `blitztext.app`
Goal: a very small landing page for an experimental open-source macOS preview.
## Hero
Headline:
> Blitztext macOS Preview
Subline:
> Speak your thoughts. Turn them into text, cleaner writing, or calmer messages.
Body:
> An experimental open-source macOS menubar app. Not finished, not hosted, not plug-and-play. Built to learn from, fork, and improve.
Primary CTA:
> View on GitHub
Secondary CTA:
> Read setup guide
Small line:
> Bring your own OpenAI API key. Optional local transcription. No hosted Blitztext backend.
## Sections
1. What it does
- Dictate
- Improve
- Calm down
- Add emojis
2. How it works
- Build the app locally
- Paste your own OpenAI API key
- Press a hotkey and speak
- Get text back on the clipboard
3. Open-source preview
- macOS-only
- MIT License
- experimental
- no warranty
- optional local transcription with user-installed WhisperKit models
4. Privacy, plainly
- online workflows send audio and text to OpenAI
- secure local mode keeps transcription on device
- no public Blitztext backend
- rewriting still uses OpenAI
- do your own review before sensitive use
5. Roadmap
- easier setup
- signed releases
- local transcription experiments
- clearer setup and security docs
- community issues
## Do Not Promise
- offline use
- production readiness
- hosted service
- free usage without API costs
- no data leaves the device
- guaranteed support
- other platforms
- bundled local models
- local rewriting
## Visual Direction
Use a real macOS screenshot or short demo GIF. Keep the page calm, sparse, and honest. Avoid fake metrics, oversized SaaS claims, and corporate origin story.

72
docs/local-models.md Normal file
View File

@ -0,0 +1,72 @@
# Local Models
Blitztext can run transcription locally with WhisperKit/CoreML. The app does not bundle a speech model, but it can download the selected compatible model from Hugging Face into the local cache.
## Recommended First Model
Use Whisper Small for the first local test. It is multilingual, supports German, and is much lighter than the large variants.
- [argmaxinc/whisperkit-coreml: openai_whisper-small_216MB](https://huggingface.co/argmaxinc/whisperkit-coreml/tree/main/openai_whisper-small_216MB)
Local cache path:
```text
~/Library/Application Support/Blitztext/models/whisperkit/openai_whisper-small_216MB
```
## Other Compatible Models
You can also install larger WhisperKit CoreML models into the same cache directory:
- [openai_whisper-large-v3-v20240930_626MB](https://huggingface.co/argmaxinc/whisperkit-coreml/tree/main/openai_whisper-large-v3-v20240930_626MB)
- [openai_whisper-large-v3-v20240930_turbo_632MB](https://huggingface.co/argmaxinc/whisperkit-coreml/tree/main/openai_whisper-large-v3-v20240930_turbo_632MB)
The app detects installed model folders that contain `AudioEncoder.mlmodelc`, `MelSpectrogram.mlmodelc`, and `TextDecoder.mlmodelc`.
## Install From The App
Open Blitztext, go to **Settings > Anpassen**, choose a local model, and click **Installieren**. You can also switch on **Sicherer Lokaler Modus** from the main popover; if the selected model is missing, Blitztext starts the download and installs it into the local cache.
After the model is installed, the Blitztext transcription workflow can run in local mode. The rewriting workflows still use OpenAI, so they are paused while secure local mode is active.
## Optional Manual Install
If you prefer the CLI path, install the Hugging Face CLI so the `hf` command is available:
```bash
python3 -m pip install --upgrade "huggingface_hub[cli]"
```
Create the local model cache:
```bash
mkdir -p "$HOME/Library/Application Support/Blitztext/models/whisperkit"
```
Download the recommended first model:
```bash
hf download argmaxinc/whisperkit-coreml \
--include 'openai_whisper-small_216MB/*' \
--local-dir "$HOME/Library/Application Support/Blitztext/models/whisperkit" \
--max-workers 4
```
Expected folder layout:
```text
~/Library/Application Support/Blitztext/models/whisperkit/
openai_whisper-small_216MB/
AudioEncoder.mlmodelc/
MelSpectrogram.mlmodelc/
TextDecoder.mlmodelc/
```
If the folder is nested differently, the app will not detect the model.
## Notes
- First use can be slower because the model has to load and prewarm.
- Local transcription avoids sending audio to OpenAI for the Blitztext workflow.
- The app currently supports local transcription only, not local rewriting.
- Models are downloaded on demand so the repository and app package stay small and auditable.

31
docs/open-source-preflight.md Normal file
View File

@ -0,0 +1,31 @@
# Open Source Preflight
Use this checklist before making the repository public.
## P0 Before Public
- Run a local build with `./build.sh --debug`.
- Run a secret scan across the working tree and commit history.
- Confirm there are no private URLs, hosted backend credentials, internal docs, or old project references.
- Keep the repository private until another maintainer has reviewed the first public commit.
- Confirm the root `LICENSE`, `README.md`, `SECURITY.md`, `CONTRIBUTING.md`, and `SUPPORT.md` are present.
- Make the preview status explicit: experimental, bring your own OpenAI API key, no hosted backend, no warranty.
- Enable GitHub private vulnerability reporting, secret scanning, and push protection before switching the repo public.
- Enable Dependabot alerts.
- Protect `main` with pull requests, at least one review, and required CI checks.
- Keep GitHub Actions permissions read-only by default.
## P1 Soon After Public
- Enable private vulnerability reporting.
- Decide whether Issues alone are enough or whether Discussions should be enabled for questions.
- Add repository topics such as `macos`, `swift`, `menubar`, `speech-to-text`, and `openai`.
- Add a lightweight release process only after the build is signed and notarized.
- Add basic tests once provider boundaries are extracted.
## P2 Later
- Add CODEOWNERS if multiple maintainers become active.
- Add local model cleanup after the in-app download/install flow.
- Consider CodeQL once the repo has enough surface area to justify scheduled scans.
- Add signed and notarized release artifacts for non-developer testers.

36
docs/privacy.md Normal file
View File

@ -0,0 +1,36 @@
# Privacy Notes
Blitztext macOS Preview does not include a hosted backend.
When you use the online workflows, your Mac sends data directly to OpenAI:
- audio recordings for transcription
- transcribed or typed text for rewriting
- custom terms and prompt context if you configured them
When **Sicherer Lokaler Modus** is enabled and a WhisperKit/CoreML model is installed, transcription runs on your Mac and does not send audio to OpenAI. Rewriting workflows still require OpenAI and are paused while secure local mode is active.
You are responsible for your OpenAI account, API usage, costs, and data handling.
## Local Data
The app stores:
- your OpenAI API key in the user's macOS Keychain
- workflow settings in local app support storage
- optional WhisperKit/CoreML model folders in local app support storage
- temporary audio files while a transcription is being processed; the app attempts to delete each recording when the workflow ends or is cancelled
Workflow output may also be placed on your clipboard so it can be pasted into another app. Auto-paste marks the clipboard entry as concealed for compatible clipboard managers and attempts to restore the previous clipboard content after paste. Clipboard managers, macOS, or other apps may still observe clipboard contents while they are present.
The app uses the system TLS trust store for OpenAI and Hugging Face requests. It does not currently pin certificates. A user-installed or managed root certificate can therefore affect HTTPS trust decisions on that Mac.
Settings such as custom prompts, custom terms, and context are stored in local app support storage as plain JSON. Do not put secrets into those fields.
## Offline Scope
Only transcription can run locally. Any workflow that rewrites, improves, or transforms text still uses OpenAI.
## Sensitive Content
Do not use this preview with confidential, regulated, or highly sensitive content unless you have reviewed the code, your OpenAI settings, and your legal/privacy requirements.

76
docs/setup.md Normal file
View File

@ -0,0 +1,76 @@
# Setup
This guide is for people who want to build and inspect the preview themselves.
## 1. Requirements
- macOS 14 or newer
- Full Xcode, with Command Line Tools installed
- XcodeGen
- Homebrew, if you want to install XcodeGen with `brew install xcodegen`
- Optional for online workflows: an OpenAI API key
- Optional for secure local transcription: a local WhisperKit/CoreML model
Install XcodeGen manually if needed:
```bash
brew install xcodegen
```
## 2. Clone And Build
```bash
git clone https://github.com/cmagnussen/blitztext-app.git
cd blitztext-app
./build.sh --debug
```
To launch after building:
```bash
./build.sh --run
```
## 3. Configure OpenAI For Online Workflows
Open the app settings and paste your own OpenAI API key if you want online transcription or rewriting workflows.
The preview currently uses:
- `whisper-1` for transcription
- `gpt-4o-mini` for lightweight rewriting
- `gpt-4o` for the calmer-message workflow
You are responsible for API access, billing, and data handling in your own OpenAI account.
Never commit your API key into this repository, issues, logs, or screenshots.
You can skip this step if you only want to test local transcription with a local WhisperKit model.
## 4. Optional Local Transcription
To use secure local transcription, choose a compatible WhisperKit CoreML model in the app and click **Installieren**. Blitztext stores models in:
```text
~/Library/Application Support/Blitztext/models/whisperkit/
```
Recommended first model: `openai_whisper-small_216MB`.
See [local-models.md](local-models.md) for the exact command, model links, and expected folder layout.
## 5. macOS Permissions
The app needs Microphone permission to record audio.
For automatic paste into the previous app, grant Accessibility permission in macOS System Settings. Without it, you can still copy and paste manually.
## Troubleshooting
- If `xcodebuild` reports that the active developer directory is only Command Line Tools, run `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`.
- If the build cannot find XcodeGen, install it explicitly with `brew install xcodegen`.
- If online transcription fails immediately, check whether the API key is present and valid.
- If secure local mode is disabled, check whether a WhisperKit model is installed in the expected folder.
- If paste does not work, check Accessibility permission.
- If audio is missing, check Microphone permission and macOS input settings.
- If you see OpenAI errors, verify model access and account billing.