# Install the Mac app and Chrome extension The Chrome extension captures Meet and Teams calls in your browser. In the Zoom web client it detects joined calls and can save Zoom’s speaker-labeled captions. The Mac app records the Teams desktop app and your microphone in desktop calls (Zoom desktop is experimental), saves every recording to disk and syncs it to your server. The two talk only over `127.0.0.1:48721`, and the extension holds no server credentials. [Capture support](/docs/index.md#capture-support) lists what each meeting app gives you. ## Install the extension For Meet and Teams calls in Chrome, open [OpenScribe in the Chrome Web Store](https://chromewebstore.google.com/detail/openscribe/hmlekoajiikkjmoncdmjmgndngcbgbjo) in the Chrome profile you use for meetings. Click **Add to Chrome** and keep the Mac app open during calls. Reach the store from **Add to Chrome** in the last Mac setup step or **Settings → Capture access**, or from **Settings → Capture setup → Install Chrome extension** on the web. On macOS, extension 0.3.7 connects in the background while the browser and Mac app are open. Older versions connect when you open the popup or a supported meeting tab. Use Node 22 to build the extension locally and Python 3.8 or newer to run its tests and package the store ZIP. Both editions connect over the same authenticated loopback bridge. The store edition requires a Mac app newer than 0.1.0 build 2. Use one edition per Chrome profile. ```bash cd apps/extension npm ci npm run build:development ``` | Command | Output | Use | | --- | --- | --- | | `npm run build:production` | `dist/production` | Store build | | `npm run package:store` | `dist/openscribe-extension--cws.zip` | Run the tests and create the verified store upload | | `npm run build:development` | `dist/development` | Local unpacked build with the development ID | | `npm run dev` | `dist/development` | Rebuilds on every change | | `npm test` | both | Builds both and runs the fixture tests | Then load it: 1. Open `chrome://extensions` and turn on **Developer mode** 2. Click **Load unpacked** and pick `apps/extension/dist/development` 3. Check that **OpenScribe** is on > [!WARNING] > Pick a `dist` folder, never `apps/extension` itself, which holds only sources. For local testing use the development ID `bnfgpacpapkllohejfcahnblgkodahnb`. For uploads use the production build, whose public key matches the existing store item `hmlekoajiikkjmoncdmjmgndngcbgbjo`. If you previously loaded a development-key build from `dist/production`, use the development folder for future local builds. Chrome scopes extension settings and site approvals to the extension ID. After a rebuild, click reload on the extension card and refresh open Meet, Teams and OpenScribe tabs. ### What the extension can access | Site | Granted | Why | | --- | --- | --- | | `meet.google.com`, Teams sites | At install | Capture the call you joined | | `*.zoom.us` | At install | Detect joined Zoom calls and read speaker-labeled captions when you start transcription | | `127.0.0.1` | At install | Reach the Mac app | | `scribe.akyonlabs.com` | At install | Let the web app talk to the extension | | `app.tactiq.io` | When you click **Allow access to Tactiq** | Import your Tactiq meetings | | Your OpenScribe server | When you approve it in the popup | Same as `scribe.akyonlabs.com`, for your server | For Zoom browser detection, update the server first, then the Mac app and extension. Chrome may ask you to approve Zoom site access when the extension updates. In a Zoom web meeting, enable **Show captions** in Zoom, then select **Start transcription** in OpenScribe. Each new caption keeps its Zoom speaker ID and display name. A correction updates that speaker’s existing line. **Stop transcription** ends collection. This path requires Zoom captions to be available in the meeting. For Meet and Teams, the popup shows the call you joined with **Start recording** or **Stop recording**. When the Mac app is not running it shows **Open Mac app**, which opens `openscribe-app://open` and brings the app to the front. ## Install the Mac app Download [OpenScribe.dmg](https://github.com/fcakyon/openscribe-releases/releases/latest/download/OpenScribe.dmg) for Apple silicon Macs with macOS 14.2 or later. Open the disk image, then double-click **OpenScribe**. It installs in Applications, opens the installed copy and ejects the disk image. An existing installation is updated in its current folder. If the system Applications folder is unwritable, a new install goes into Applications in your home folder. If OpenScribe is recording, it keeps recording and the installed copy stays as it is. To build from source you need macOS 14.2 and the Xcode Command Line Tools. ```bash ./apps/macos/scripts/build-app.sh open ./apps/macos/dist/OpenScribe.app ``` The script builds a release binary and writes `OpenScribe.app` (bundle ID `com.akyonlabs.openscribe`). Local builds use an ad-hoc signature. Set `OPENSCRIBE_SIGNING_IDENTITY` to a Developer ID Application identity to sign with hardened runtime, a secure timestamp and the microphone entitlement. Set `OPENSCRIBE_SIGNING_KEYCHAIN` to select a specific signing keychain. Pass a folder to choose the output location. > [!IMPORTANT] > Open the installed app before you grant permissions. Ad-hoc rebuilds change the identity macOS approved. Moving to Developer ID signing may require one new permission grant and Keychain approval. Later releases must retain the bundle ID and compatible signing requirements. Check actual access in the app before repairing an existing permission entry. ## Updates Release builds check for a new version every four hours and download it in the background. OpenScribe relaunches into it without a prompt while no call, recording or meeting reminder is active, the app is in the background and **Remember sign-in on this Mac** is on. Until then, **Restart to Update** in the menu bar menu, the OpenScribe menu and **Settings → About** installs it now, and is unavailable during a call, recording or workspace connection. Otherwise the update installs the next time you quit. Builds before 0.1.1 cannot update themselves, so download the app once from **Settings → Capture setup** on the web. ## Prepare a signed DMG Release preparation needs a Developer ID Application identity and a notarization credential profile in the Mac Keychain. Configure the profile once with `xcrun notarytool store-credentials openscribe`, using an Apple app-specific password or App Store Connect API key. Keep credentials out of scripts and shell history. The install window comes from `dmgbuild` 1.6.7, which needs Python 3.10 or later on your `PATH`, for example through `uv tool install dmgbuild==1.6.7`. ```bash OPENSCRIBE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)" \ OPENSCRIBE_VERSION=0.1.0 OPENSCRIBE_BUILD_NUMBER=2 \ bash apps/macos/scripts/release-dmg.sh ``` The command builds and signs the app, notarizes and staples `OpenScribe.app`, packages it as the only app in `apps/macos/dist/OpenScribe.dmg`, submits the DMG to Apple, staples the ticket, checks Gatekeeper acceptance on both bundles, and verifies any signed Sparkle feed against the embedded `SUPublicEDKey` (when `OPENSCRIBE_SPARKLE_PRIVATE_KEY` is set, `OPENSCRIBE_SPARKLE_PUBLIC_KEY` is also required). Use a higher build number for each release. `OPENSCRIBE_NOTARY_PROFILE` selects a profile other than `openscribe`. Push a new version tag such as `v1.2.3` to start the Apple silicon release workflow. The native tests run first. The release job validates secrets up front, signs and notarizes both `OpenScribe.app` and `OpenScribe.dmg`, validates their stapled tickets, checks Gatekeeper, verifies `SUPublicEDKey` and the signed Sparkle feed, then creates a GitHub release with the DMG and `appcast.xml`. If a release or draft already exists for the tag, the job stops before signing. A manual workflow run runs the native tests and verifies an ad-hoc Apple silicon app bundle. Configure the Developer ID certificate, App Store Connect notary key, Sparkle key pair and distribution repository token in the source repository’s `macos-release` GitHub environment. The workflow lists the exact secret names. [Release workflow](https://github.com/fcakyon/openscribe/blob/main/.github/workflows/macos-release.yml). ## Sign in from the Mac Sign in on your Mac to sync recordings to your workspace and see your calendars. The Mac app signs in through your browser and never holds a Google secret. 1. Click **Sign In** in the app or in **Settings** 2. Your browser opens `/pair` on your server. Sign in there if you are not already 3. The page connects the app to the account signed in on the web, with no code to check, and shows **Mac app connected**. The request expires after 10 minutes The page hands a one-time grant to the app through `127.0.0.1`, so it only works in a browser on the same Mac. A `/pair` link opened on another device cannot connect anything. Connecting saves the session in the login Keychain (service `com.akyonlabs.openscribe`) without a Keychain prompt, so the app stays signed in across restarts and updates. Turn off **Remember sign-in on this Mac** in **Settings** to keep it in memory only. Only that switch, or the **Remember Sign-In** button on the notice that appears when macOS needs your confirmation for a new app build, can show the Keychain prompt. Active Mac sessions silently renew their token before expiry on launch, app activation, wake and periodic checks without Keychain interaction. If a session expires, live transcription and cloud sync pause while local audio stays saved on your Mac, and clicking **Sign In** during an active call reconnects your current workspace and resumes live transcription. Signing out removes the saved session. From a terminal: ```bash security delete-generic-password -s com.akyonlabs.openscribe -a app_session_token ``` ## Use your own server A new install connects to `https://scribe.akyonlabs.com`. When no meeting is active, click **Use Another Workspace…** on the sign-in screen or open **Settings → Workspace → Change Workspace…**, enter your server address and click **Connect**. The app opens sign-in on that server in your browser and switches workspaces after approval. Changing workspaces or switching accounts stays unavailable until an active meeting ends. If the server enables [email sign-in](/docs/self-hosting.md#sign-in-without-google), use the email and password set by its admin. You cannot change workspace during an active meeting, and recordings stay with the workspace they came from. Use the same published Chrome extension for every workspace. It sends captured audio to the Mac app, which syncs it to the connected server. Approve a self-hosted web origin from the extension popup when you need web features like Tactiq import. The app reads the address in this order: 1. `OPENSCRIBE_SERVER_URL` in the launch environment, for development 2. The saved workspace (`serverBaseURL` in the `com.akyonlabs.openscribe` defaults) 3. `https://scribe.akyonlabs.com` Connect calendars on the web, then pick which ones the Mac shows in **Settings → Calendars**. Copies of the same occurrence across selected calendars appear once. Upcoming also shows meetings saved in OpenScribe without a calendar. **Upcoming** retries transient errors right away and in the background, and checks again on wake, network recovery, or when you return to the Mac app. Choose **Retry** to refresh immediately, or **Open Calendar on Web** if the problem persists. When an account needs access again, choose **Reconnect on Web**, then **Reconnect** beside that account. Multiple failures show a shared summary (`Some calendars didn’t sync`, `2 calendars need access`, or `Couldn’t refresh calendars`). Each event shows its time, and its calendar account when you connect two or more. **Join** appears on an event with a call link that is in progress or starts within 10 minutes. Click an event for its details, which keep **Join Meeting** whenever the event has a call link. Hover over an event or move to it with Tab to show its **…** menu, or Control-click the event. The menu hides one event or a whole recurring series. Restore them on the Mac under **Settings → Calendars → Hidden events → Manage…**, or on the web under **Settings → Preferences → Hidden events → Manage**. Hiding syncs with the web and keeps your saved meeting notes and recording-to-meeting matching. Working-location entries such as **Home** and other Calendar status blocks stay out of the agenda. Real all-day events show **All day**. **Settings → Preferences → Time format** switches between **Auto**, **12-hour** and **24-hour** on the web and Mac. Auto uses AM/PM for US IPs and 24-hour time elsewhere, with 24-hour as the fallback when country information is unavailable. ## Set up on first launch Until you sign in and allow the Mac access recording needs, the window shows only setup, one centered step at a time. 1. **Carry less.** asks you to **Sign In** in your browser. **Use Another Workspace…** connects a self-hosted server 2. **Allow recording** lists the Mac access recording needs. Each row has its own button, which turns into a green **Enabled** once macOS grants it. **Continue** stays off until every row is enabled 3. **Add OpenScribe to Chrome** installs the browser extension and connects your calendar | Step | Row | Button | | --- | --- | --- | | 2 | Record your voice | **Enable Microphone** | | 2 | Detect calls | **Enable Accessibility** | | 3 | OpenScribe extension | **Add to Chrome** | | 3 | Calendar | **Connect** | The extension records Google Meet and Teams in your browser. Step 3 opens the store in your default browser when it installs from the Chrome Web Store, otherwise in the first such browser on your Mac, and the title and button name that browser. When one of these browsers is installed, **Continue** stays off until the extension connects to the app, which extension 0.3.7 does in the background. With older versions, open the popup or a supported meeting tab to connect. After you click **Add to Chrome**, a small spinner beside the button shows that the app is waiting, and the button stays so you can open the store again. The row then shows **Connected**. On a Mac without such a browser, step 3 shows only the calendar. The calendar is optional, and **Connect** opens Calendar on the web. On your first sign-in with Accessibility and Microphone already granted, step 3 still appears once unless the extension is already connected and a calendar is linked. If you sign out or macOS removes a permission later, the window returns to setup, except while a call records, which keeps its page and **Stop**. **Settings → Capture access** shows the same controls. On a Mac with Chrome or another Chromium browser, its **Meet and Teams in Chrome** row shows **Connected** while the extension is connected. Otherwise it shows **Connects while Chrome is open** until Chrome has been open alongside OpenScribe for at least 40 seconds, then offers **Add to Chrome**. The row uses your setup browser’s name. ## Grant macOS permissions Setup and **Settings → Capture access** show an **Enable** button for anything missing. macOS asks for system audio itself, the first time a Zoom or Teams desktop call records. | Permission | Asked when | Used for | | --- | --- | --- | | Microphone | **Enable Microphone**, or you record a Zoom or Teams desktop call | Your voice in Zoom and Teams desktop calls | | System audio recording | A Zoom or Teams desktop call records for the first time, also when recording starts by itself | The meeting app's remote audio | | Accessibility | **Enable Accessibility** | Seeing which meeting app and window is active | | Screen Recording | **Enable Screen Recording** in Settings | Optional window screenshots | **Enable Microphone** shows the macOS Allow dialog the first time. After that it opens the Microphone pane with a panel docked at the bottom of the System Settings window, pointing you to turn **OpenScribe** on in the list above it. **Enable Accessibility** opens the Accessibility pane with a panel docked at the bottom of the System Settings window. Drag **OpenScribe** from that panel into the list above it. If OpenScribe is already listed but not working, remove it with − and drag it in again. **Enable Screen Recording** shows the macOS permission prompt the first time, which lists **OpenScribe** under **Screen & System Audio Recording**. Clicking it again opens that pane with the same docked panel, so you can turn OpenScribe on or drag it in. ## During and after a meeting **Join a scheduled call.** Upcoming can remind you one minute before a selected Meet, Zoom or Teams event and again when it starts. The second reminder stays available until the event ends, including when your Mac wakes mid-meeting. Dismiss clears the current reminder. OpenScribe suppresses reminders for a call it already matches to the active meeting. Choose **Browser** or **Desktop app** under **Join Zoom and Teams in** in Preferences on web or Mac. Browser is the default. The Mac uses the browser when the desktop app is unavailable. **Recording starts by itself.** With **Start recording automatically on join** on in Mac Settings, which is the default, recording starts as soon as the app sees that you joined a call. | Call | Starts by itself | | --- | --- | | Zoom or Teams desktop app | Yes, once **Meeting detection** is connected. Without microphone access it waits instead of asking in the middle of the call | | Meet or Teams in Chrome | Yes, once the extension reports that you joined | | Zoom in Chrome | No. Choose **Start Transcription** | | Meet or Teams in Chrome without the extension | No. The **Meeting detected** prompt offers **Enable Extension**, and Live prompts you to install or turn on the Chrome extension | | Slack huddle | No. The **Meeting detected** prompt offers **Start Recording** | If you install or turn on the Chrome extension while already inside a Google Meet call, OpenScribe warns you in both the extension popup and the Mac Live view to rejoin the call so other participants' audio can be captured. Each call starts by itself only once. **Stop** keeps that call stopped, and closing the **Meeting detected** prompt with its × keeps the call from starting by itself. **Record** still starts it. With the setting on, a Zoom or Teams desktop recording stops when the app reports the call over. OpenScribe keeps a native session through a lobby, a missing toolbar or a failed read while call activity is uncertain. If the app is running, automatic stop requires two observations at least two seconds apart with neither joined controls nor active input or output from that app. Quitting the call app ends the automatic recording on the next scan. A browser recording stops when you leave the call. With the setting off, nothing starts by itself, and a desktop recording you start runs until you click **Stop**. **Recording indicator.** With the setting on, a small floating panel shows **Recording**, the elapsed time, the meeting app and **Stop** while a call records. Click it to open the call in OpenScribe. It never takes focus and hides while OpenScribe is in front on Live. Zoom in Chrome shows no indicator. **Meeting detected prompt.** It offers **Start Recording**, **Start Transcription** for Zoom in Chrome, or **Enable Extension** when a Chrome Meet or Teams call is missing the extension, plus **Open Notes**, which opens the notes for this call. **Join reminders and call prompts** in Mac **Settings → Recording** turns this prompt and the calendar reminder on or off. It does not hide the recording indicator. **Meeting page.** During a call, **Live** shows the meeting title, the meeting app such as **Google Meet**, chips for people, links and files, and one notes document. Your notes save on this Mac as you type, then sync to that meeting in your workspace, even if the call ends before the upload finishes. Drop or paste a file, image or web link anywhere on the page, or choose **Attach**, to add it to the call. Click a chip to open its link or preview its file. **Enhance Notes.** Writes a summary and action items from your notes and the transcript, and shows them in place of your notes. Switch between **My Notes** and **Summary** at any time. Your own text never changes. The summary and action items are also saved to the meeting on the web, the same as summarizing it there. **Enhance Notes** appears once the call is saved to your workspace and needs sign-in. Local microphone audio uses the platform participant marked as you when that identity is available. Teams in Chrome supplies its local signaling identity, and native Teams and Zoom supply their labeled self participant. Meet self identity is still unverified. **Teams in Chrome.** During recording OpenScribe requests Teams live captions for remote speech. Each final line uses the participant ID supplied by Teams and the time it arrived. Your own microphone uses your configured speech model. If Teams does not supply named captions, the Mac keeps the receiver audio locally. **Transcript.** The recording pill at the bottom left shows the elapsed time and **Stop**, or **Record** when the call is not recording. Its arrow, there for the whole call except while you type in Ask, slides the live transcript up over your notes, with each line under the speaker OpenScribe could attribute, the microphone the meeting uses and a language menu. There is no microphone picker, because OpenScribe follows the meeting's own choice. The camera menu takes meeting screenshots. **Ask about the call.** Click **Ask anything** beside the recording pill and type a question (Return sends, Shift-Return starts a new line), or choose **Catch Me Up** or **Questions to Ask**. While the field has focus, it takes the whole bar. Questions and answers stay above the field as one thread for the call, each answer with the call times it draws on. Closing the panel keeps a pending answer, and the field reads **Replying…** until it arrives. A follow-up question also sends the earlier questions and answers of the same Ask thread. Ask needs sign-in and is ready once the call is saved to your workspace. Questions and answers are saved with the meeting in your workspace, not in your notes. | | While the meeting runs | After it ends | | --- | --- | --- | | Write notes, add links, files, screenshots | In the Mac app | On the web meeting page | | Edit your notes | In the Mac app | On the web | | Remove links and files | On the web | On the web | | Mac app shows | The meeting page under **Live** | The same page, read-only, under **Last Call** until your next call, with only **Open meeting on web** in the bar | **Past.** Lists your earlier meetings with their date and length, such as **30 min**. Click one to open it on the web. A meeting with items still to upload reads **Not synced**. With no meetings yet, Past shows **No meetings yet** and **Import Meetings**. Transcript word times use the meeting’s original clock across Record and Stop. Live uploads preserve partial-to-final order, so a slow partial cannot replace a final. A capture warning means a possible gap, even if later audio resumes. Each item is saved on disk with its meeting before the app shows it as saved. Uploads still queued when the call ends go to that same meeting. Each join has a capture session. When its meeting link matches one selected calendar occurrence, leaving and rejoining that occurrence keeps the same web meeting. Later occurrences using the same link remain separate. Ambiguous or unavailable calendar matches stay separate. Record and Stop retain the current session. Rejoins retain separate local recording folders, while their transcripts, notes and files share the meeting timeline and one Past entry. Opening that entry retries pending uploads from all its captures. The Mac retries session updates after a connection failure and publishes the original capture clock before replaying saved transcripts. A session recovered after an app interruption is marked stopped without inventing an end time. ## Local recordings Everything is written locally before upload: ```text ~/Library/Application Support/OpenScribe/recordings// ├── manifest.json session, participants, streams ├── transcript.jsonl transcript segments ├── notes.jsonl notes document and links ├── attachments.jsonl file metadata ├── capture-errors.jsonl capture failures ├── attachments/ copied files ├── screenshots/ window captures └── streams/ 48 kHz mono audio per stream ├── .pcm 16-bit, flushed per chunk ├── .f32 32-bit float ├── .packets.jsonl packet timing └── .wav built at stop or recovery ``` At launch the app rebuilds missing WAV files from the PCM, reloads sessions and retries pending uploads to their original meeting. Delete a session folder to delete that recording from the Mac. ## How the extension talks to the app All traffic stays on `127.0.0.1:48721`. Every route answers `403` to a browser origin other than the extension's. Local tools without an `Origin` header can read `/api/status`, `/api/call` and `/api/calendar/next`. `/api/auth/complete` takes only the sign-in grant for the request this app started. | Route | Purpose | | --- | --- | | `GET /api/status` | Is the app running | | `GET` or `POST /api/extension/pair` | Get a bridge token. Only the extension gets one | | `ws://127.0.0.1:48721/ws/extension` | Presence, roster and audio frames | | `POST /api/extension/event` | Same frames when the WebSocket is down | | `GET /api/call` | Current call state: `active`, `idle` or `unknown` | | `GET /api/calendar/next` | Next meeting from your selected calendars or meetings saved without a calendar | | `GET /api/auth/complete?id&grant` | Finish browser sign-in, then redirect back to your workspace | ```bash curl -s http://127.0.0.1:48721/api/status # {"ok":true,"app":"OpenScribe","port":48721,"signedIn":true,...} ``` ## Import from Tactiq Connect Tactiq once on the web import page. The Chrome extension checks for new calls daily while Chrome is available. If Chrome was closed when a check was due, it catches up when it can reach the same signed-in OpenScribe workspace and Tactiq account. **Sync now** checks sooner. **Disconnect** stops future checks. Daily discovery reads **My Meetings** and exports new transcripts from the signed-in Tactiq site. It skips meetings already imported and meetings you removed. A different signed-in Tactiq account cannot send meetings to this connection. For tl;dv, connect your API key on the same page. The server checks for new meetings daily, including when Chrome is closed. 1. The page asks the extension through a small script it runs on approved OpenScribe sites 2. Without Tactiq access, the page shows **Allow access to Tactiq**. The extension opens a page with **Allow OpenScribe to read your Tactiq meetings**, Chrome asks once, and the import continues 3. The extension reads your meetings in an `app.tactiq.io` tab, opening one in the background if needed. Your Tactiq sign-in token never leaves that tab 4. Unfinished, draft and preview meetings are skipped. Archived ones are kept 5. A background tab the extension opened closes one minute after the last request. Your own tabs stay open | Page message | Reply | | --- | --- | | `import_ping` | `{ok, version, sources: ["tactiq"], tactiq_identity: true}` | | `import_list` with `cursor` | `{ok, account_email, items: [{external_id}], next_cursor}`, `null` cursor on the last page | | `import_fetch` with `external_id` | `{ok, raw: {meeting, transcript, account_email}}` | | `import_connect` | Opens the access page | | `import_daily_*` (`identity`, `schedule`, `list`, `fetch`, `done`, `cancel`) | Schedules browser alarms, verifies the signed-in Tactiq account, pages **My Meetings** and normalizes TXT exports | | Any failure | `{ok: false, error}` with `needs_permission`, `signed_out`, `account_mismatch`, `unavailable`, `source_error`, `forbidden_origin` or `no_extension` | ## Approve a self-hosted site The store build works with your own server after one approval: 1. Open your OpenScribe site and click the OpenScribe toolbar button 2. Click **Let (your site) import your meetings through OpenScribe** 3. Accept Chrome's prompt The extension remembers that exact origin and port. Remove the site's access at `chrome://extensions` to revoke it. A site on `127.0.0.1` needs no Chrome prompt, because the extension already holds that host for the Mac app. Approve only servers you trust with your Tactiq meetings. ## Command-line modes | Flag | Does | | --- | --- | | none | Starts the app with its window, Dock icon and menu bar item | | `--self-test` | Checks timeline mapping, local storage, the local bridge, the setup gate, the notes document, the meeting prompt, the recording indicator and the Accessibility guide, then exits | | `--detect-once` | Prints Accessibility trust, microphone permission, detected meeting apps and the meeting window count as JSON | | `--snapshot [store]` | Renders light and dark UI screenshots into `` | Run them on `./apps/macos/dist/OpenScribe.app/Contents/MacOS/OpenScribe`.