Skip to content
OpenScribe Docs
Mac app and Chrome extension

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 lists what each meeting app gives you.

Install the extension#

For Meet and Teams calls in Chrome, open OpenScribe in the Chrome Web Store 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
CommandOutputUse
npm run build:productiondist/productionStore build
npm run package:storedist/openscribe-extension-<version>-cws.zipRun the tests and create the verified store upload
npm run build:developmentdist/developmentLocal unpacked build with the development ID
npm run devdist/developmentRebuilds on every change
npm testbothBuilds 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

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#

SiteGrantedWhy
meet.google.com, Teams sitesAt installCapture the call you joined
*.zoom.usAt installDetect joined Zoom calls and read speaker-labeled captions when you start transcription
127.0.0.1At installReach the Mac app
scribe.akyonlabs.comAt installLet the web app talk to the extension
app.tactiq.ioWhen you click Allow access to TactiqImport your Tactiq meetings
Your OpenScribe serverWhen you approve it in the popupSame 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 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.

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.

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, 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
StepRowButton
2Record your voiceEnable Microphone
2Detect callsEnable Accessibility
3OpenScribe extensionAdd to Chrome
3CalendarConnect

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.

PermissionAsked whenUsed for
MicrophoneEnable Microphone, or you record a Zoom or Teams desktop callYour voice in Zoom and Teams desktop calls
System audio recordingA Zoom or Teams desktop call records for the first time, also when recording starts by itselfThe meeting app's remote audio
AccessibilityEnable AccessibilitySeeing which meeting app and window is active
Screen RecordingEnable Screen Recording in SettingsOptional 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.

CallStarts by itself
Zoom or Teams desktop appYes, once Meeting detection is connected. Without microphone access it waits instead of asking in the middle of the call
Meet or Teams in ChromeYes, once the extension reports that you joined
Zoom in ChromeNo. Choose Start Transcription
Meet or Teams in Chrome without the extensionNo. The Meeting detected prompt offers Enable Extension, and Live prompts you to install or turn on the Chrome extension
Slack huddleNo. 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 runsAfter it ends
Write notes, add links, files, screenshotsIn the Mac appOn the web meeting page
Edit your notesIn the Mac appOn the web
Remove links and filesOn the webOn the web
Mac app showsThe meeting page under LiveThe 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/<sessionId>/
├── 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
    ├── <stream>.pcm     16-bit, flushed per chunk
    ├── <stream>.f32     32-bit float
    ├── <stream>.packets.jsonl  packet timing
    └── <stream>.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.

RoutePurpose
GET /api/statusIs the app running
GET or POST /api/extension/pairGet a bridge token. Only the extension gets one
ws://127.0.0.1:48721/ws/extensionPresence, roster and audio frames
POST /api/extension/eventSame frames when the WebSocket is down
GET /api/callCurrent call state: active, idle or unknown
GET /api/calendar/nextNext meeting from your selected calendars or meetings saved without a calendar
GET /api/auth/complete?id&grantFinish 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 messageReply
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_connectOpens 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#

FlagDoes
noneStarts the app with its window, Dock icon and menu bar item
--self-testChecks 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-oncePrints Accessibility trust, microphone permission, detected meeting apps and the meeting window count as JSON
--snapshot <dir> [store]Renders light and dark UI screenshots into <dir>

Run them on ./apps/macos/dist/OpenScribe.app/Contents/MacOS/OpenScribe.

View as Markdown