Tapes

Tapes is a local-first audio recording app. You record in the browser. Your recordings stay on your own devices and sync across your local network with Automerge CRDTs. There is no central database.

The desktop app is the sync host. It stores the shared data and serves the recording UI to other devices on the LAN. Those devices join as guests by scanning a QR code, and record into the same library.

Recorded audio is not carried in the Automerge document. The bytes are stored on the host and addressed by their sha-256 hash. The document holds only a descriptor for each recording. Guests upload what they record and fetch what they play over the host's /blobs endpoint.

Monorepo layout

This is a Turborepo monorepo managed with Yarn 4.

Apps

Package	Description	Dev port
apps/web-client	Vite and React shell that mounts the Tapes app and captures microphone audio.	3000
apps/electron-client	Desktop host. Embeds web-client and runs the LAN sync server.	—
apps/api	Standalone NestJS Automerge sync server. An alternative remote backend.	3031
apps/web	Next.js marketing site.	3002
apps/docs	Next.js documentation site.	3001
apps/identity	Static passkey ceremony page, served at identity.tapes.network.	3003

The host's embedded sync server listens on port 9001 by default. If that port is taken it uses whatever port the OS hands it. Set TAPES_SYNC_SERVER_PORT to pick a different one.

Packages

Package	Description
@tapes-monorepo/core	The Tapes application itself: App, views, context, sync helpers and QR pairing.
@tapes-monorepo/provenance	Signed statements about recordings: types, canonical JSON and Ed25519 signing.
@tapes-monorepo/sync-protocol	What a guest and a host must agree on to open a sync socket. Plain TypeScript.
@tapes-monorepo/ui	Shared presentational React components, styled with Tailwind.
@tapes-monorepo/tailwind-config	Shared Tailwind theme.
@tapes-monorepo/eslint-config	Shared ESLint configurations.
@tapes-monorepo/typescript-config	Shared tsconfig.json bases.

The UI lives in packages/core/app/. Both web-client and the electron renderer mount it, so the same app runs in a browser and inside the desktop host.

Architecture

flowchart LR
    subgraph host["Desktop host (electron-client)"]
        renderer["Renderer<br/>(@tapes-monorepo/core)"]
        sync["Embedded Automerge<br/>sync server :9001"]
        renderer <--> sync
    end

    subgraph guest["Guest device (browser)"]
        webclient["web-client<br/>(@tapes-monorepo/core)"]
    end

    api["apps/api<br/>NestJS sync server :3031"]

    webclient -- "ws/wss (LAN)" --> sync
    renderer -. "optional remote sync" .-> api
    webclient -. "optional remote sync" .-> api

Each shell builds its own Automerge repo. It hands the repo to core's providers and renders App inside them. Storage and networking are platform-specific, so only the shell knows where its sync server lives.

• The web client stores documents in IndexedDB. It talks to other tabs over a broadcast channel and to the host over a WebSocket.
• The host's embedded sync server stores documents and blobs on the filesystem.
• Guests reach the host over the LAN. In development the web-client dev server proxies /sync and /blobs to it. See apps/web-client/vite.config.ts.
• apps/api is an independent, filesystem-backed sync server. It can act as a remote backend. Its auth module is currently commented out.

Prerequisites

• Node.js 24. The version is pinned in .nvmrc.
• Yarn 4, declared in packageManager. Run corepack enable once so the pinned version is used.
• macOS for the full recording flow. The dev scripts read the LAN IP with ipconfig getifaddr en0. The desktop host shells out to SoX to record and to switchaudio-osx to select an input. On Linux and Windows the non-audio parts build and run, but end-to-end recording is not supported.

Getting started

corepack enable   # once, to activate the pinned Yarn 4
yarn              # install dependencies
yarn dev          # start all apps in dev mode

Local HTTPS

Browsers only expose the microphone and OPFS in a secure context. LAN guests therefore cannot record over plain HTTP. Use HTTPS on the LAN IP instead:

yarn dev:https

That script starts ui, core, web-client, the electron host and api. The web client gets TLS from @vitejs/plugin-basic-ssl. The host advertises an https://<lan-ip>:3000 URL to guests.

The embedded sync server stays on plain HTTP here. Guests do not reach it directly in development. They load the Vite dev server, which proxies through to it over loopback, and both hops are already secure contexts. So the host certificate authority described below does not come into play under yarn dev:https.

apps/api serves over HTTPS in development. It expects localhost-key.pem and localhost-cert.pem in apps/api/. Generate them with yarn workspace api cert.

LAN HTTPS in the packaged app

In the packaged app guests connect to the embedded sync server directly, so that server needs its own certificate. The host is its own certificate authority. It mints a root once and issues the server certificate from it. Guests either install that root once or click through a browser warning. Both are supported.

See the electron-client README for what each option protects against, and for the page a host can send a guest to.

Scripts

Run these from the repo root. Each one fans out through Turborepo.

Command	Description
yarn dev	Start all apps in dev mode.
yarn dev:https	Start the LAN recording surfaces over HTTPS.
yarn build	Build all apps and packages.
yarn lint	Lint everything.
yarn check-types	Type-check everything.
yarn test	Run unit tests.
yarn format	Prettier-format every .ts, .tsx and .md file.
yarn clean	Remove build artifacts.

Versioning and releases

Versioning uses Changesets. Add a changeset when your change affects a published package:

yarn changeset

On push to main the Release workflow opens or updates a "Version Packages" pull request that applies the pending changesets. Dependency updates are automated with Renovate.

CI

Pull requests to main run two jobs. See .github/workflows/ci.yml.

• Build & Lint runs yarn lint, yarn check-types and yarn build, then the unit tests for core, electron-client and web-client. The apps/api Jest suite is excluded because of a pre-existing compile failure.
• E2E (web-client) runs Playwright against Chromium. The job first starts PulseAudio with two virtual sources, so the mic-capture tests have inputs to enumerate and switch between.

The electron end-to-end suite runs nightly instead of per pull request, on a macOS runner. It packages the desktop app and records through SoX, which is slow and macOS-only. See .github/workflows/e2e-electron.yml. You can also trigger it by hand.

Documentation

Each app and package has its own README with setup and environment details. Contribution guidelines are in CONTRIBUTING.md. Guidance for AI agents is in CLAUDE.md.