CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Local audio/video transcription CLI — no cloud, no API keys. Outputs markdown with timestamps.

Language conventions: code identifiers in English; docstrings, comments, UI strings, and commit messages in Russian. Style is ruff-compatible. Commits follow Conventional Commits.

Commands

uv sync                            # install dependencies
uv run transcribe meeting.mp4      # run CLI
uv run pytest                      # run all tests
uv run pytest tests/test_cli.py    # run one test file
uv run pytest -k test_name         # run single test by name
uv run pytest -v                   # verbose output

Package manager is uv (not pip). Build backend is hatchling.

Architecture

CLI (cli.py)
  → config.py      cascade: CLI arg → .transcriber.toml → device-aware default → hardcoded
  → utils.py       detect_device(), validate files, expand globs (Windows workaround)
  → transcriber.py load_model() → get_backend(device) → ensure_model_available → create_model
                    _transcribe_file() with mid-stream CUDA→CPU fallback
  → formatter.py   segments → markdown with timestamps, paragraph grouping (>2s pause or >60s)

Backend system (`src/local_transcriber/backends/`)

Three backends implement the Backend Protocol (structural typing, no inheritance required):

Backend	Module	Devices	Library
FasterWhisper	`faster_whisper.py`	`cpu`, `cuda`	`faster_whisper` (CTranslate2)
OpenVINO	`openvino.py`	`openvino`, `openvino-gpu`, `openvino-cpu`	`openvino_genai`
OnnxAsr	`onnx_asr.py`	`onnx`	`onnx_asr` (onnxruntime)

get_backend(device) in backends/__init__.py maps device string to backend with lazy imports.

Key design decisions

Two-level fallback: GPU→CPU at model load time AND mid-stream during transcription (GPU visible via nvidia-smi but insufficient VRAM).
CUDA bootstrap (_cuda_bootstrap.py): preloads libcublas.so.12 via ctypes.CDLL(RTLD_GLOBAL) before importing ctranslate2, because pip's nvidia-cublas-cu12 installs to a non-standard path and LD_LIBRARY_PATH can't be changed at runtime (glibc caches it).
Batch mode: 3-phase pipeline (prescan → load model once → transcribe all). TranscribeFileResult carries updated model/backend/device state between files.
Device-aware defaults: compute_type and model vary by device (float16 for CUDA, int8 for OpenVINO, float32 for CPU). Defined in config.py DEVICE_DEFAULTS.
OpenVINO uses pre-quantized models — compute_type selects which HF repo to download, not a runtime parameter.

Testing

All tests mock backends — no real model downloads or transcription. Key test patterns:

CLI tests: typer.testing.CliRunner + mocks for load_config, detect_device, load_model, _transcribe_file, write_transcript
_single_patches() — helper assembling standard happy-path mock set
_make_result() / _make_tfr() — factories for test data

Common tasks

New CLI option: add typer.Option in cli.py:main() → add key to HARDCODED_DEFAULTS in config.py → write test
New audio/video format: add extension to SUPPORTED_EXTENSIONS in utils.py
New backend: implement Backend protocol → add device mapping in backends/__init__.py → add device-aware defaults in config.py
Change output format: edit format_transcript() in formatter.py

Project docs

docs/PRD.md — product requirements and scope
docs/backlog.md — future experiments and ideas
docs/gpu.md — GPU benchmarks, platform compatibility details
docs/adr/ — architecture decision records (CUDA bootstrap, batch mode, pluggable backends, compute-type defaults, ONNX-ASR evaluation)

3.9 KiB Raw Blame History