Project
Contributing to Ghira
Set up a development build, run the checks, follow the conventions
Thanks for helping. Ghira is Apache-2.0 licensed, and every contribution is made under that license.
Development setup
| Tool | Version |
|---|---|
| Rust | pinned in rust-toolchain.toml (rustup installs it) |
| Node.js | 22+ |
| pnpm | pinned in package.json (corepack enable) |
| CMake | 3.26+ (NeMo-Speech.cpp) |
| macOS | Xcode (Apple Silicon for Metal) |
| Windows | Visual Studio 2022 Build Tools (C++), WebView2 |
git clone https://github.com/nhtera/Ghira.git && cd Ghira
git submodule update --init # not --recursive: NeMo-Speech.cpp nests large/LGPL repos we don't use
pnpm install
pnpm build # frontend (needed before cargo builds the desktop crate)
cargo test --workspace
pnpm --filter @ghi/desktop tauri dev # run the desktop appSpeech engines (optional, needed for real ghi transcribe|diarize|bench):
./tools/scripts/build-nemo.sh # NeMo-Speech.cpp into target/nemo (Metal on macOS)
./tools/scripts/fetch-models.sh # pinned models into ./models (~850 MB, SHA-256 checked)
cargo test -p ghi-speech -p ghi-cli --features ghi-cli/nemo
cargo build --release -p ghi-cli --features nemo # target/release/ghiAudio capture: crates/ghi-audio needs CMake (it builds libopus)
and, on macOS, the Xcode Swift toolchain: its build.rs compiles
native/macos/GhiAudioMac with swift build. To record on this Mac:
cargo build -p ghi-cli && codesign -s - -f target/debug/ghi # binds the embedded Info.plist
target/debug/ghi record --mode call --duration 10 --out /tmp/rec # prompts for mic + System Audio RecordingStorage: crates/ghi-store builds SQLCipher; on Windows and Linux
it also builds OpenSSL, which needs Perl (Apple targets use CommonCrypto).
Debug builds of ghi keep a store's key ring in <dir>.devkey
instead of the Keychain (GHI_KEYSTORE=keychain to use it); release builds
never contain that code path (tools/scripts/check-no-dev-key.sh).
Before opening a PR, run what CI runs:
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
pnpm lint && pnpm typecheck && pnpm test
./tools/scripts/check-spdx.sh
./tools/scripts/check-net-egress.sh
cargo deny check licenses bans advisories sourcesIf you change the website or the docs (apps/website/, docs/, or the root
documents the docs publish), also run the site's checks. The site is a
separate npm project (Node 22.18 or later), not part of the pnpm workspace;
see apps/website/README.md:
npm --prefix apps/website ci --ignore-scripts
npm --prefix apps/website run lint && npm --prefix apps/website run typecheck && npm --prefix apps/website test
npm --prefix apps/website run build:site && npm --prefix apps/website run check-links
npm --prefix apps/website run test:browser # once: npx --prefix apps/website playwright install chromiumA docs page is published only when docs/README.md lists it.
Conventions
- License header. Every source file starts with
// SPDX-License-Identifier: Apache-2.0(#for shell/Python). - Naming. Rust:
snake_case. TypeScript/JS files:kebab-case. - Commits. Conventional Commits
(
feat:,fix:,docs:...). - Typed commands. Tauri commands use tauri-specta. After changing one, run
GHI_UPDATE_BINDINGS=1 cargo test -p ghi-desktopand commitapps/desktop/src/bindings.ts.
Rules that CI enforces
- Network access only in
crates/ghi-net. No HTTP clients or sockets anywhere else, and nofetch/WebSocketin the webview. The app's CSP allows no remote origins. See PRIVACY.md. - No telemetry, analytics or remote fonts/assets.
- Dependency licenses. Allowed: Apache-2.0, MIT, BSD-2/3-Clause, ISC, Zlib, MPL-2.0, OFL-1.1, Unicode-3.0, CC0-1.0. Not allowed in shipped binaries: GPL, AGPL, SSPL, LGPL (static), non-commercial or "source-available". No bundled FFmpeg.
- No models or recordings in git. Models are downloaded at a pinned revision and SHA-256. Eval recordings are private and never committed.
Reporting security issues
Don't open a public issue. See SECURITY.md.
Code of conduct
This project follows the Contributor Covenant.
Edit this page on GitHubLast updated