Getting started

Make a short test recording before using Ambient for a conversation you need to keep. This checks your permissions, input device and system-audio capture together.

Install a release

Prebuilt downloads are being refreshed for the public launch. Use Build from source until a new signed release is available. The steps below apply to that release.

Release builds target Apple Silicon Macs running macOS 14.4 or later. Allow roughly 1 GB for the extracted app and models, plus storage for recordings.

1. Download a ZIP from Releases.
2. Unzip it and move Ambient.app into /Applications.
3. Open Ambient from Applications.
4. Open its menu bar item, then choose Open Ambient to show the window.

The models are bundled; you do not need Rust, Node or fetch-models.sh for a release build. macOS permissions are separate from the app’s recording controls. Allow Microphone and System Audio Recording when requested. If a prompt is missing or a track is silent, use troubleshooting.

Make a test recording

1. Choose Start Recording from the menu bar, or Record (⌘R) at the top of the window’s sidebar.
2. Speak a short sentence and play a short piece of audio on the Mac.
3. Check that the Room and Call levels respond.
4. Choose Stop and wait for transcription to finish.
5. Select the session in the window and check the transcript.

You can open the session during recording to read completed speech turns. Text arrives in blocks, with additional delay for model loading or ongoing speech. After Stop, Ambient finishes the remaining text and speaker labels. The menu shows queued work, so a new recording can start while the previous one finishes.

Use Reveal in Finder to inspect the session files. The audio/ directory contains separate room and call tracks. Verify both if the transcript is missing speech. A successful build or a clean probe does not prove capture works.

Work with the transcript

The sidebar lists sessions. Search names and tags there, or use ⌘K to search transcript text. Rename a session, add notes, pin it or apply tags above the selected transcript.

Tidied shows the recognition output with naming edits applied; Verbatim shows the original recognition output. Use Separate voices to group speakers when audio is still available, then assign names. Copy Markdown and Export let you take the transcript elsewhere.

Speaker labels and words can be wrong. Review them before sharing the transcript. Settings covers devices, watched apps and retention; what is kept explains deletion and the limits of local storage.

Build from source

You need macOS 14.4 or later, the Xcode Command Line Tools and Rust installed through rustup. rust-toolchain.toml selects the compiler. The models occupy about 670 MB; allow additional space for the download archive and build artifacts.

git clone https://github.com/jasonm4130-labs/ambient.git
cd ambient
./fetch-models.sh
cargo run --release --bin ambient -- probe
./setup-signing.sh
./make-app.sh
open -a "$PWD/build/Ambient.app"

setup-signing.sh creates a stable local signing identity. It can ask for keychain access. make-app.sh assembles and signs the bundle; a local development signature is not a notarized distribution build.

Launch the bundle to record system audio. A binary started directly in a terminal can receive silent buffers because macOS attributes the capture request to the wrong process. Repeated ad-hoc signing can also invalidate an earlier permission grant. Follow troubleshooting if capture is silent.

The committed UI bundle means Node is not required for a Rust-only build. For UI and docs changes, see the contributor guide.

Use the CLI

Commands that read files or inspect the machine can run in a terminal:

cargo run --release --bin ambient -- sessions
cargo run --release --bin ambient -- transcribe \
  models/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8 audio.wav

For a release installed in Applications, use its executable directly for those commands:

/Applications/Ambient.app/Contents/MacOS/ambient sessions

Recording commands must go through the app bundle. Quit an already-running Ambient instance before launching it with CLI arguments: open otherwise activates the existing process without applying those arguments.

open -a "$PWD/build/Ambient.app" --args record --name test

Stop that recording from another terminal:

cargo run --release --bin ambient -- stop

The command reference describes export formats, environment variables, naming, speaker separation and diagnostics.