Skip to content

Standardize README #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jay739 merged 1 commit into from
Jul 15, 2026
Merged

Standardize README #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 41 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,28 @@

Self-hosted, GPU-accelerated transcription with speaker labels. An open-source alternative to Otter.ai that runs entirely on your own hardware.

- **Whisper large-v3** via [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (CTranslate2, CUDA, int8_float16)
- **Speaker diarization** via [pyannote.audio](https://github.com/pyannote/pyannote-audio) (optional, needs a free Hugging Face token)
- **Web UI**: drag and drop a file, watch progress, read a color-coded transcript
- **API**: upload, poll, fetch results as JSON
- **CLI**: `scribe transcribe meeting.mp3 --diarize -f srt`
- **Exports**: TXT, SRT, VTT, JSON, Markdown

No cloud, no accounts, no per-minute billing. Your audio never leaves the machine.

## Features

| Feature | Detail |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Transcription | Whisper large-v3 via [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (CTranslate2, CUDA, int8_float16) |
| Speaker diarization | [pyannote.audio](https://github.com/pyannote/pyannote-audio), optional; without it scribe still transcribes and reports why labels are missing |
| Web UI | Drag and drop a file, watch progress, read a color-coded transcript |
| API | Upload, poll, fetch results as JSON |
| CLI | `scribe transcribe meeting.mp3 --diarize -f srt` |
| Exports | TXT, SRT, VTT, JSON, Markdown |

## Requirements

- NVIDIA GPU with CUDA support (tested on an RTX 3060 Ti, 8 GB VRAM). CPU works but is slow.
- Windows or Linux, Python 3.12 (the setup script installs its own via [uv](https://github.com/astral-sh/uv))
- Roughly 6 GB of disk for models on first run

## Quick start (Windows)
## Install

### Quick start (Windows)

```powershell
git clone https://github.com/jay739/scribe && cd scribe
Expand All @@ -29,34 +35,46 @@ Then open http://localhost:8323.

### Speaker diarization setup

Diarization uses `pyannote/speaker-diarization-3.1`, which is a gated model:
Diarization uses a gated Hugging Face model, so it needs a one-time token setup:

1. Create a free token at https://huggingface.co/settings/tokens
2. Accept the conditions at https://huggingface.co/pyannote/speaker-diarization-3.1 and https://huggingface.co/pyannote/segmentation-3.0
3. Put the token in `.env`: `SCRIBE_HF_TOKEN=hf_...`
2. Accept the conditions at https://huggingface.co/pyannote/speaker-diarization-community-1
3. Put the token in `.env` at the repo root: `SCRIBE_HF_TOKEN=hf_...`

Without a token scribe still transcribes, it just cannot tell speakers apart.

## CLI
## Usage

### CLI

```powershell
.venv\Scripts\python -m scribe.cli transcribe path\to\audio.mp3 --diarize -f srt -o out\
```

### Web UI and API

Run the server (`python -m scribe.server`) and open http://localhost:8323 for the drag-and-drop UI, or drive it programmatically: upload a file, poll the job, then fetch the result in any export format.

## Configuration

Everything is an environment variable (or a line in `.env` at the repo root):
Every setting is an environment variable, or a line in `.env` at the repo root:

| Variable | Default | Meaning |
| -------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `SCRIBE_MODEL` | `large-v3` | Whisper model size (`tiny` ... `large-v3`) |
| `SCRIBE_DEVICE` | `cuda` | `cuda` or `cpu` |
| `SCRIBE_COMPUTE` | `int8_float16` | CTranslate2 compute type |
| `SCRIBE_HF_TOKEN` | unset | Hugging Face token for diarization (falls back to `HF_TOKEN`, then the standard Hugging Face token cache) |
| `SCRIBE_DIARIZATION_MODEL` | `pyannote/speaker-diarization-community-1` | Diarization pipeline to load |
| `SCRIBE_HOST` | `127.0.0.1` | Server bind address; set `0.0.0.0` to expose on the network |
| `SCRIBE_PORT` | `8323` | Server port |
| `SCRIBE_DATA_DIR` | `./data` | Uploads, results, job database |
| `SCRIBE_MODELS_DIR` | `./models` | Model cache (`HF_HOME` points here) |

## Contributing and security

| Variable | Default | Meaning |
| ------------------- | -------------- | ------------------------------------------ |
| `SCRIBE_MODEL` | `large-v3` | Whisper model size (`tiny` ... `large-v3`) |
| `SCRIBE_DEVICE` | `cuda` | `cuda` or `cpu` |
| `SCRIBE_COMPUTE` | `int8_float16` | CTranslate2 compute type |
| `SCRIBE_HF_TOKEN` | unset | Hugging Face token for diarization |
| `SCRIBE_PORT` | `8323` | Server port |
| `SCRIBE_DATA_DIR` | `./data` | Uploads, results, job database |
| `SCRIBE_MODELS_DIR` | `./models` | Model cache (HF_HOME points here) |
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and checks. Report vulnerabilities privately per [SECURITY.md](SECURITY.md).

## License

MIT
MIT, see [LICENSE](LICENSE).
Loading