Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Scribe Audio Collection

Multilingual clinical speech with Whisper drafts and human-reviewed transcripts and English translations, built for fine-tuning speech-to-English models.

Reviewers

You listen to recordings and correct the text Whisper produced, using an app that runs on your own computer. Setup takes a few minutes and you only do it once.

1. Get access

Create a free Hugging Face account and send your username to the maintainer, who'll give you access.

2. Install the tools

You need two tools: Git and uv. uv sets up Python for you, so you don't need to install Python yourself.

  • Mac: brew install git uv
  • Windows: in PowerShell, winget install Git.Git astral-sh.uv, then open a new terminal.
  • Linux: Git from your package manager, then curl -LsSf https://astral.sh/uv/install.sh | sh.

3. Start the app

git clone <this repo>
cd scribe_dump
uv run review_server.py

The first run takes a minute while uv downloads what the app needs, then the app opens in your browser at http://127.0.0.1:4321. Keep the terminal open while you work, and press Ctrl-C there to stop. Next time, run uv run review_server.py from the same folder.

Using a coding agent (Claude Code, Codex, Cursor or similar)? Give it this prompt instead of doing steps 2 and 3 yourself:

Set up the Scribe review app on my computer. If this repo isn't cloned yet, clone
<this repo> first. Then follow "Setting up the review app" in its CLAUDE.md: check and
install the tools, run the app, and confirm it's working. Don't ask for my Hugging Face
token. I'll paste it into the app myself.

AGENTS.md points agents to the same instructions.

4. Connect Hugging Face

The first time, the app asks for an access token:

  1. Open your access tokens and choose Create new token.
  2. Choose the Write type and give it any name.
  3. Paste it into the app. It's stored on your computer only. Don't share it with anyone.

5. Start reviewing

Open Reviewer guide in the app's sidebar. It takes you through claiming a batch, reviewing clips and submitting your work. docs/reviewing.md has the same steps without screenshots. How it works, also in the sidebar, explains what each step does on Hugging Face.

Maintainers

I want to Go to
Add new recordings docs/ingesting-a-collection.md
Create batches, or merge and finalise reviews docs/maintaining.md
Publish to Hugging Face docs/huggingface.md
Understand the fields and statuses design_spec.md
See what reviewers are told docs/reviewing.md, and the in-app guide at app/public/guide.html
Change what coding agents do here CLAUDE.md, which AGENTS.md points to
Run the tests Tests

The dataset isn't in this repo. Audio, flac/, peaks/ and metadata.json are git-ignored and stay local. The published copy is ohcnetwork/scribe_dataset.

Layout

Path What
build_metadata.py incremental ffprobe scan of audio/ → metadata.json
segment_audio.py audio/ → seekable flac/, and segments of 28 s or less cut at pauses
extract_peaks.py flac/ → peaks/<id>.json waveforms
transcribe.py Whisper large-v3 per segment: transcript and English translation, resumable
hf_export.py corpus → hf/, ready to upload (docs/huggingface.md)
review_admin.py maintainer: make batches, merge reviews, finalise
review_server.py reviewer: local server behind the review app
app/ the review app (React, Vite)
app/dist/ the built app, committed so reviewers don't need Node. Rebuild with make app
reviewers.txt Hugging Face usernames whose reviews are accepted
migrate_schema_v2.py one-off v1 → v2 metadata migration; keeps metadata.v1.json
tests/, app/e2e/ checks, run with make test

Prerequisites

  • ffmpeg and ffprobe on PATH (brew install ffmpeg).
  • Python 3.11+. extract_peaks.py uses audioop, which Python 3.13 removed.
  • uv for make review, the same command reviewers run.
  • Node 18+, only to change the review app. After editing anything in app/, run make app and commit app/dist/ with your change. make test fails if you forget.
  • Whisper: pip install -r requirements.txt (Apple Silicon). The ~3 GB model downloads on the first run.

Processing audio

To add recordings, see docs/ingesting-a-collection.md. make ingest COLLECTION=<name> runs these steps in order:

python3 build_metadata.py    # add new files to metadata.json; --collection names them
python3 segment_audio.py     # FLAC and segments
python3 extract_peaks.py     # waveforms
python3 transcribe.py        # both Whisper tasks; --limit N to smoke-test
python3 -m tests.test_metadata   # durations and segments are sane

Every step is incremental and safe to re-run. transcribe.py is safe to stop with Ctrl-C. Durations come from the audio packets themselves, because broken container timestamps inflate what ffmpeg reports; corrupt marks those clips. segment_audio.py rebuilds their timeline, so they're usable like any other clip.

Tests

make test                                                      # everything offline
SCRIBE_LIVE_REPO=<you>/<test-repo> python3 -m tests.test_review_live   # against the real Hub

Run tests from the repo root as modules (python3 -m tests.<name>), so they can import the scripts. tests/test_review_ui.py drives the committed build in Chrome with real audio. It needs ffmpeg and cd app && npm ci.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages