Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Contributing to Oatcake

Thanks for helping. Oatcake records people's calls, so a change is judged first on whether it keeps
their recordings, notes and voices safe and on their Mac, and then on whether it's easy to use.

## Before you start

For anything bigger than a small fix, open an issue first and say what you'd like to change, so we
can agree on the approach before you spend time on it. [What's next](docs/whats-next.md) lists what
we'd like to add.

## Setting up

You need an Apple Silicon Mac on macOS 15 or later, and Xcode's command line tools with Swift 6.2
or later (`xcode-select --install`). Xcode itself isn't needed.

```sh
swift build # debug build of everything
swift test # the core's tests
Scripts/bundle.sh # build/Oatcake.app, with the recorder and llama.cpp inside
```

[Development](docs/development.md) has the details, including how to
[try a build](docs/development.md#trying-a-build) without touching your own recordings, settings
and voiceprints: start it with `OATCAKE_DATA_DIR` pointing at another folder, and choose another
Meetings folder in its Settings. A development copy shares an installed Oatcake's bundle ID, so
leave its notification buttons alone: a click can reach the installed copy.

If `swift test` fails with "plugin for module 'TestingMacros' not found", the build folder is
stale: run `rm -rf .build` and try again.

## Making a change

- Branch from `trunk`, named for what the branch does: `add/…` for something new, `fix/…` for a
fix, `chore/…` for anything else.
- Put logic in `Sources/OatcakeCore`, where it can be tested, and keep `Sources/Oatcake` to the
app's windows and menus. Add or change tests in `Tests/OatcakeCoreTests` (a file for each area)
for what you change.
- Without Xcode, SwiftUI's `@State` macro isn't available, so views use the `ViewState` alias.
- Write comments that say why, not what.
- Anything the app says to people (buttons, hints, notifications, errors) is in plain British
English: say what happens and what to do next, without jargon.
- Use made-up names in code, tests, fixtures, docs and screenshots: John Doe, Jane Doe, John
Smith, Jane Smith, Joe Bloggs, Richard Roe and the like. Never use a real person's name, and
never commit a real recording, transcript or calendar.
- A change people can see or use goes in the docs in the same pull request: the page in
[docs/](docs/) that describes it, and [Features](docs/features.md) if it adds or removes a
feature.

## Commits and pull requests

- Write each commit subject as a sentence about what changes for the person using Oatcake, such
as "A voice that isn't part of the call can be left out in Who's who". Leave out prefixes like
`feat:`.
- Keep a pull request to one change, and say what it does, why, and how you tested it.
- For a change you can see, add before and after screenshots, taken with a test copy and made-up
names.
- The Test workflow builds everything, runs the tests and checks the scripts parse on every pull
request. A pull request from a fork waits for a maintainer to start its test run.
- An automated review comments on each pull request. Answer or fix what it finds before asking
for a merge.
- Maintainers merge with a merge commit.

## Releases

Releases are made by maintainers from `trunk`: see [Releasing](docs/releasing.md).

## Licence

Oatcake is GPL-3.0-or-later. By contributing, you agree that your contribution is licensed under
the same terms ([LICENSE](LICENSE)). Code adapted from elsewhere needs a licence that allows it,
and a note in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
742 changes: 63 additions & 679 deletions README.md

Large diffs are not rendered by default.

71 changes: 71 additions & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Development

How to build Oatcake, try a build without touching your own data, and find your way around the
code. [CONTRIBUTING.md](../CONTRIBUTING.md) covers pull requests.

## Build from source

Needs Xcode's command line tools (`xcode-select --install`, Swift 6.2 or later); Xcode itself
isn't needed.

```sh
swift build # debug build of everything
swift test # the core's tests (Tests/OatcakeCoreTests, a file for each area)
Scripts/bundle.sh # build/Oatcake.app, release build, recorder and llama.cpp inside
Scripts/bundle.sh debug # the same, debug build
```

`Scripts/bundle.sh` signs with the "Oatcake Release" certificate when that's in your keychain,
and ad-hoc otherwise. macOS ties the recorder's microphone and system-audio permission to the
signature: an ad-hoc build is a new app to macOS every time (so it asks again), and only a
release-signed copy can update itself. `OATCAKE_SIGN_IDENTITY` and `OATCAKE_SIGN_KEYCHAIN` choose
another identity or keychain, `OATCAKE_REQUIRE_SIGNING=1` stops rather than sign ad-hoc, and
`OATCAKE_BIN` names a folder of binaries already built (the Release workflow uses these). The
icon is `assets/icon.svg`; `assets/Oatcake.icns` is built from `assets/icon.png` with `iconutil`.

`Scripts/bundle.sh` also puts llama.cpp's server in the app: one fixed build from llama.cpp's
releases, downloaded once into `.build/llama` and checked against its SHA-256. A copy run straight
from `swift build` has no llama.cpp beside it; point `OATCAKE_LLAMA_DIR` at a folder that holds
`llama-server` and its libraries (`build/Oatcake.app/Contents/Resources/llama` will do).

With only the command line tools, SwiftUI's `@State` macro isn't available (its plugin ships with
Xcode), so views use the `State` property wrapper through the `ViewState` alias.

## Trying a build

To try a build without touching your own recordings, settings and voiceprints, point it at
another data folder (and set a different Meetings folder in its Settings):

```sh
open -n --env OATCAKE_DATA_DIR=/tmp/oatcake-test build/Oatcake.app
```

Environment variables that help when trying things out:

- `OATCAKE_DATA_DIR` points a development copy at another data folder, with its own saved calendar
address. A copy started with it leaves the login Keychain alone.
- `OATCAKE_LLAMA_DIR` names the folder llama.cpp's server is in, for a copy that isn't a bundle.
- `OATCAKE_CALENDAR_URL` gives it a calendar address without saving one (a local `.ics` served
over HTTP will do).
- `OATCAKE_CALL_APPS` names a file listing the apps to treat as on a call, one per line, so the
call notice and the automatic stop can be tried without making a call.
- `OATCAKE_UPDATE_FEED` points the updater at another `latest.json` (see
[Releasing](releasing.md)).

A development copy has the same bundle ID as an installed Oatcake, so macOS can hand a click on
one of its notification buttons to the installed copy, which then acts on your own data. Leave a
test copy's notifications alone.

## Layout

- `Sources/OatcakeRecorder/` — system-audio + mic recorder (helper app)
- `Sources/RecorderContract/` — the files the recorder and Oatcake pass between them, and the
check that the recorder only records for Oatcake
- `Sources/OatcakeCore/` — recordings, speech pipeline, voiceprints, the language model and its
download, summaries and templates, meeting folders, renaming speakers, calendar and its private
address, Granola and Quill imports, Ask, updates
- `Sources/Oatcake/` — the app (SwiftUI); `--analyse` runs the analysis helper, `--live` the live
transcript's and `--menu-bar` the menu bar item's
- `Tests/OatcakeCoreTests/` — tests, a file for each area, including the calendar against
ical.js's output
- `Scripts/` — bundling, versioning, signing `latest.json`
114 changes: 114 additions & 0 deletions docs/features.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Features

Everything Oatcake does today, with a link to where each is described. Planned work is in
[What's next](whats-next.md).

## Recording

- Records your microphone as you and everything the Mac plays (Zoom, Meet, Slack, a browser) as
the other people, through a small helper app that only records for Oatcake.
[Record](how-it-works.md#1-record)
- Notes during the call, one point per line, each stamped with the time you started typing it and
editable afterwards. [Record](how-it-works.md#1-record)
- Prep notes typed or pasted before the call, carried into its notes.
[Record](how-it-works.md#1-record)
- The open to-dos from the latest earlier meeting in the same folder on the record screen, to tick
off.
[Record](how-it-works.md#1-record)
- Live transcript beside your notes, transcribed on the Mac as the call goes.
[Live transcript](how-it-works.md#live-transcript)
- Microphone choice, following the Mac's or a chosen mic, changeable mid-call without a gap in the
recording. [Record](how-it-works.md#1-record)
- Warnings for a silent microphone, no call audio, or a recorder that stopped or never started, on
screen and as notifications; what was recorded is kept. [Record](how-it-works.md#1-record)
- An offer to record when a calling app starts using the microphone, and an automatic stop when
the call ends, with **Keep recording**. [Calls are noticed](how-it-works.md#calls-are-noticed)
- The running time and **Stop Recording…** in the menu bar, including over full-screen apps.
[The menu bar](how-it-works.md#the-menu-bar)
- A recording carries on if Oatcake crashes, and is picked up if it opens again within ten minutes.
[Security](security.md)

## Calendar

- Your calendar's next calls under Upcoming in the sidebar, from its private iCal address.
[Calendar settings](settings.md#calendar)
- Clicking a call opens New recording for it, in the folder named like it or a new one for a
recurring meeting. [Calendar settings](settings.md#calendar)
- **Join the call** for Meet, Zoom and Teams links. [Calendar settings](settings.md#calendar)
- A reminder 5 minutes before each call, whose button opens the call and starts recording.
[Calendar settings](settings.md#calendar)
- Your next call in the menu bar, with what's coming up in its menu.
[The menu bar](how-it-works.md#the-menu-bar)
- Events that aren't calls left out by their title ("Focus time", "Out of office"…) or by "Oatcake
ignore" in the title. [Calendar settings](settings.md#calendar)
- One event, one occurrence, or a series from then on ignored from Upcoming's right-click menu,
and brought back from Settings. [Calendar settings](settings.md#calendar)
- The calendar's address kept in a file only your account can read.
[Security](security.md)

## Transcription and voices

- Transcription on the Mac's Neural Engine, in English or 25 European languages.
[Process](how-it-works.md#2-process), [Speech models](models.md#speech-models)
- The call side split into voices, with your microphone's echo of the call dropped.
[Process](how-it-works.md#2-process)
- Voices recognised from earlier calls by their fingerprints, and names suggested from the
conversation for the rest. [Process](how-it-works.md#2-process)
- Who's who: play each voice's clips, name it (or pick someone from the invite), merge voices,
mark one as several people, or leave out one that isn't part of the call.
[Review](how-it-works.md#3-review-whos-who)
- Saving straight after processing instead, with a summary or the transcript only, and naming the
voices later. [Saving without Who's who](how-it-works.md#saving-without-whos-who)
- **Rename Speakers** for a saved meeting: put a wrong name right, name a "Voice 2", swap two
names or make two speakers one. [Rename Speakers](how-it-works.md#rename-speakers)
- People Oatcake recognises listed in Settings, to rename or forget. [People](settings.md#people)

## Summaries and to-dos

- A summary and to-dos written by a language model on this Mac, steered by your notes, in the
background after the meeting is saved. [Save](how-it-works.md#4-save),
[Language model](models.md#language-model)
- Your own summary instructions, to-do instructions and jargon. [Summaries](settings.md#summaries)
- Summary templates for different kinds of meeting, picked per meeting.
[Regenerate and summary templates](how-it-works.md#regenerate-and-summary-templates)
- Regenerate the summary or the to-dos alone. [Regenerate and summary
templates](how-it-works.md#regenerate-and-summary-templates)
- **Write summary** to try again when one couldn't be written. [Save](how-it-works.md#4-save)
- To-dos with owners and due dates, ticked off in the meeting; a to-do's time opens the transcript
there. [To-dos](how-it-works.md#to-dos)
- A To-dos page gathering every meeting's, by due date, folder or owner, with your own list
besides. [To-dos](how-it-works.md#to-dos)
- To-dos can be turned off altogether. [General](settings.md#general)
- Qwen3 8B or 4B, downloaded and run by Oatcake, or a model server of your own on your Mac or
network. [Language model](models.md#language-model)

## Meetings

- Each meeting a folder of Markdown (`summary.md`, `todo.md`, `transcript.md`, `notes.md`) and
`meeting.json` in a Meetings folder you choose, kept in step with Finder.
[Save](how-it-works.md#4-save)
- Summary, Transcript and My notes tabs, each rendered or as editable Markdown.
[Reading and editing](how-it-works.md#reading-and-editing)
- **Copy** and **Share**, formatted for documents and mail and as Markdown.
[Reading and editing](how-it-works.md#reading-and-editing)
- Folders within folders, meetings dragged between them, several at a time; rename, Show in
Finder and Move to Trash. [Organising meetings](how-it-works.md#organising-meetings)
- Search across every meeting, and find in the transcript you're reading.
[The window](how-it-works.md#the-window)
- Bigger and smaller text. [The window](how-it-works.md#the-window)
- The call's audio kept with the meeting, if you choose. [Storage](settings.md#storage)

## Ask

- Questions about the meeting you have open or across all of them, answered by the model on this
Mac, with links to the meetings and times it drew on. [Ask](how-it-works.md#5-ask)
- Follow-ups in the same conversation, as you move between meetings. [Ask](how-it-works.md#5-ask)

## Getting started and staying up to date

- Install with one Terminal line, or by hand. [Install](install.md)
- Import from Granola's export and Quill's backup. [Importing](importing.md)
- Updates from signed releases, checked daily and installed when you choose.
[Updates](updates.md)
- Moving from the Electron version (0.3 and earlier) in place.
[Moving from Electron](moving-from-electron.md)
Loading
Loading