Local transcription
Local audio/video transcription with Whisper large-v3, speaker diarization, and an agent skill for substantive proofreading. Produces comparable raw and proofread TXT/SRT files without sending audio to a hosted service.
The CLI runs the media and speech models locally. The invoking agent reads the resulting text, proposes corrections, and uses the CLI to apply them to both formats. This is not an autonomous local language-model proofreader: the agent may be cloud-hosted and the transcript becomes part of its context.
Setup
Requires Python 3.11+ and uv. FFmpeg and FFprobe install automatically: macOS wheels include native tools for Apple Silicon and Intel, while Linux/Windows use a binary dependency. macOS 13+ is targeted; CI tests Python 3.13 on macOS 15 (both architectures) and Linux x86-64. The default is CPU int8 inference; Apple GPU/Metal acceleration is not implemented. Allow approximately 4 GB for models plus the Python environment and working audio. Long recordings can take substantial CPU time.
Install the CLI from PyPI without cloning the repository:
uv tool install --python 3.13 local-transcription==0.1.4
uv tool update-shell
local-transcription models install
local-transcription doctor --verify
If your current shell cannot find the command yet, reopen it or use the executable inside the directory printed by uv tool dir --bin. The installation includes ready-to-run FFmpeg and FFprobe binaries; Mac users need neither Homebrew nor Rosetta. The CLI prefers existing system tools and otherwise uses the packaged binaries without changing PATH or requiring administrator access. Model weights are installed separately. The package provides an executable CLI command, not a standalone native binary.
The repository and GitHub release downloads are public. See the installation guide for the portable skill archive and an alternative installation with exact runtime constraints. Standard PyPI installation resolves dependencies from package metadata; the release constraints reproduce the versions in our lockfile.
To reuse an existing model directory instead of downloading the same weights:
local-transcription models install --from-dir /path/to/existing/models
The default cache is $XDG_CACHE_HOME/local-transcription/models, or ~/.cache/local-transcription/models. Override it using --models-dir or LOCAL_TRANSCRIPTION_MODELS. Setup verifies SHA-256 checksums; doctor --verify can verify them again. Downloads occur only through models install.
Use
# Full recording, automatic language and speaker count
local-transcription transcribe /path/to/meeting.webm
# Audio input; disable speaker analysis
local-transcription transcribe /path/to/interview.mp3 --no-diarization
# Known language and speaker count
local-transcription transcribe /path/to/meeting.mkv --language ru --speakers 2
# Extract audio alone, detecting the source format by its contents
local-transcription convert /path/to/video.bin
# Recheck a difficult passage without changing the transcript
local-transcription recheck /path/to/meeting.transcription --start 05:55 --end 06:15
# Apply agent-reviewed, word-specific corrections
local-transcription apply-review /path/to/meeting.transcription /path/to/edits.json
transcribe creates a new <stem>.transcription folder next to the input. Repeated runs use -2, -3, etc. --output-dir changes the requested folder, with the same collision protection. The input and previous results remain unchanged.
| Artifact | Produced by |
|---|---|
<stem>.audio.<extension> |
Video audio extraction; stream copy when supported, FLAC fallback |
<stem>.txt, <stem>.srt |
Local transcription and optional speaker analysis |
<stem>.proofread.txt, <stem>.proofread.srt |
Agent review followed by apply-review |
<stem>.summary.md |
Skill, only after the user requests or confirms a summary |
work/ |
PCM audio, canonical words, model output, review handoff, diagnostics |
Text remains in the spoken language. Speaker labels and tooling are in English. With diarization disabled, output omits speaker labels rather than calling every speaker “unknown.” Diagnostics never appear as a transcript appendix.
Install the skill
The release archive local-transcription-skill.zip contains the skill and all its reference documents. Extract it into ~/.agents/skills/ after checksum verification. Inspect any existing local-transcription destination before replacing it.
For development, keep the canonical skill in this repository and install an absolute symlink from the checkout:
mkdir -p ~/.agents/skills
ln -s "$(pwd)/skills/local-transcription" ~/.agents/skills/local-transcription
Invoke the skill by name or ask the agent to transcribe a local recording with proofread subtitles. It uses an installed CLI or an existing development environment, completes all four transcript files, then asks about a summary. If the CLI is missing, the skill installs the packaged release without cloning the repository.
Documentation
- CLI and troubleshooting
- Architecture and offline boundary
- Review schema and editorial policy
- Model sources and third-party notices
- Validation and observed limitations
Development
gh repo clone ihoru/local-transcription
cd local-transcription
uv sync --locked
uv run --locked pytest
uv run --locked ruff check .
On macOS, a source/editable installation compiles FFmpeg during setup and requires Xcode command line tools. Normal PyPI wheel installation requires no compiler.
Run the development CLI with uv run --locked local-transcription. See release packaging to build the installable wheel and portable skill.
CI runs deterministic tests with synthetic media. Real speech evaluations run locally; personal recordings, transcripts, and model weights are excluded from the repository. No open-source license has been selected for the project code. Third-party components retain their own licenses.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file local_transcription-0.1.4.tar.gz.
File metadata
- Download URL: local_transcription-0.1.4.tar.gz
- Upload date:
- Size: 92.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
41f0971d5e2002d20deea3ca2dc05971bf68e70db4b99146d36e68d8d25b8f6e
|
|
| MD5 |
07b35233baf40953a5b66b8f192669d9
|
|
| BLAKE2b-256 |
a95c69025f212709efbb7aa21e661ec020cd7a4a7d06d90c9e3ab6711dbebcdc
|
Provenance
The following attestation bundles were made for local_transcription-0.1.4.tar.gz:
Publisher:
publish.yml on ihoru/local-transcription
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
local_transcription-0.1.4.tar.gz -
Subject digest:
41f0971d5e2002d20deea3ca2dc05971bf68e70db4b99146d36e68d8d25b8f6e - Sigstore transparency entry: 2710164925
- Sigstore integration time:
-
Permalink:
ihoru/local-transcription@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Branch / Tag:
refs/tags/v0.1.4 - Owner: https://github.com/ihoru
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Trigger Event:
release
-
Statement type:
File details
Details for the file local_transcription-0.1.4-py3-none-macosx_13_0_x86_64.whl.
File metadata
- Download URL: local_transcription-0.1.4-py3-none-macosx_13_0_x86_64.whl
- Upload date:
- Size: 33.1 MB
- Tags: Python 3, macOS 13.0+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8a80fe90070abb74f510e85d145d1a6fef8bfff69f4a519ee35c4dc4002fb3b1
|
|
| MD5 |
43aa206fd1a08f256d41d25abd328ab1
|
|
| BLAKE2b-256 |
dc01b2043ce9a447f97cdedb33382511a6a7bccaf9fdd2906cc26872e0120dd2
|
Provenance
The following attestation bundles were made for local_transcription-0.1.4-py3-none-macosx_13_0_x86_64.whl:
Publisher:
publish.yml on ihoru/local-transcription
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
local_transcription-0.1.4-py3-none-macosx_13_0_x86_64.whl -
Subject digest:
8a80fe90070abb74f510e85d145d1a6fef8bfff69f4a519ee35c4dc4002fb3b1 - Sigstore transparency entry: 2710165519
- Sigstore integration time:
-
Permalink:
ihoru/local-transcription@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Branch / Tag:
refs/tags/v0.1.4 - Owner: https://github.com/ihoru
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Trigger Event:
release
-
Statement type:
File details
Details for the file local_transcription-0.1.4-py3-none-macosx_13_0_arm64.whl.
File metadata
- Download URL: local_transcription-0.1.4-py3-none-macosx_13_0_arm64.whl
- Upload date:
- Size: 32.1 MB
- Tags: Python 3, macOS 13.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ca3b0a6da54b3964128a19e071d6aebc67d302add7a1f5270419243a3c9adecd
|
|
| MD5 |
cac40c601327f8e1bad675719586ff1a
|
|
| BLAKE2b-256 |
837a87fd15c379e6dbfd3cbc028adae97962a1ad286c53bb2ed18b0ab4975d8c
|
Provenance
The following attestation bundles were made for local_transcription-0.1.4-py3-none-macosx_13_0_arm64.whl:
Publisher:
publish.yml on ihoru/local-transcription
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
local_transcription-0.1.4-py3-none-macosx_13_0_arm64.whl -
Subject digest:
ca3b0a6da54b3964128a19e071d6aebc67d302add7a1f5270419243a3c9adecd - Sigstore transparency entry: 2710165422
- Sigstore integration time:
-
Permalink:
ihoru/local-transcription@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Branch / Tag:
refs/tags/v0.1.4 - Owner: https://github.com/ihoru
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Trigger Event:
release
-
Statement type:
File details
Details for the file local_transcription-0.1.4-py3-none-any.whl.
File metadata
- Download URL: local_transcription-0.1.4-py3-none-any.whl
- Upload date:
- Size: 20.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0fad99036500274fdb771abb4b8d6e6ee25c078de824ef998a15ed80574eb738
|
|
| MD5 |
509c7419c7cc34761f529cb2c034f58b
|
|
| BLAKE2b-256 |
6424dc4814b75016dbaace632730b1da007394293673b8f3bf01b074c381cb79
|
Provenance
The following attestation bundles were made for local_transcription-0.1.4-py3-none-any.whl:
Publisher:
publish.yml on ihoru/local-transcription
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
local_transcription-0.1.4-py3-none-any.whl -
Subject digest:
0fad99036500274fdb771abb4b8d6e6ee25c078de824ef998a15ed80574eb738 - Sigstore transparency entry: 2710165225
- Sigstore integration time:
-
Permalink:
ihoru/local-transcription@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Branch / Tag:
refs/tags/v0.1.4 - Owner: https://github.com/ihoru
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@35984188da7f4c5ccac94b6b06ea2f4f2aa1bffd -
Trigger Event:
release
-
Statement type:
