Skip to content

environment-variables.md

Latest commit

 

History

History
100 lines (81 loc) · 6.43 KB

environment-variables.md

File metadata and controls

100 lines (81 loc) · 6.43 KB
Raw

Environment Variables

A single reference for the environment variables transcribe.cpp recognizes, split by audience. The library follows one parse convention for boolean toggles: a flag is on when it is set, non-empty, and its first character is not 0 (so FOO=1, FOO=on, FOO=yes are on; FOO=0, FOO= and unset are off). Path-valued vars are off when unset or empty.

Tier 1 — runtime configuration

Compiled into every build, including release. These are operational knobs, not build-gated. Note that TRANSCRIBE_DUMP_DIR — while it ships — is still a tensor-dumping debug/validation hook: enabling it does per-tensor device→host copies and writes raw activations to disk, so it carries I/O cost and a data-leak surface. Leave it unset in production unless you are deliberately collecting dumps.

The two TRANSCRIBE_TEST_*_THROW fault-injection hooks also ship in release binaries on purpose: wheel clean-install CI proves exception containment against the exact artifact users install (see AGENTS.md, "C ABI Exception Discipline"). Unlike the boolean convention above, any non-empty value arms them (including 0); unset or empty is inert. Leave them unset outside of tests.

Variable Effect
TRANSCRIBE_NO_FLASH Disable flash attention on encoder and decoder (forces the manual F32 path).
TRANSCRIBE_FORCE_FLASH Force flash attention on. Wins over TRANSCRIBE_NO_FLASH if both are set.
TRANSCRIBE_CONV_DIRECT_DW / TRANSCRIBE_CONV_NO_DIRECT_DW Force the depthwise-conv dispatch to the direct conv_2d_dw path / the im2col path, overriding the per-family backend default.
TRANSCRIBE_CONV_DIRECT_PW / TRANSCRIBE_CONV_NO_DIRECT_PW Force the pointwise-conv dispatch to direct mul_mat / im2col, overriding the backend default.
TRANSCRIBE_DUMP_DIR=<dir> Enable the per-stage tensor dumper; writes <name>.f32 + <name>.json per dumped tensor into <dir>. The basis for the numerical-comparison harness (scripts/compare_tensors.py).
TRANSCRIBE_PERF_DEBUG Print a per-stage timing breakdown to stderr (DEBUG log) on the families that profile (cohere, granite, canary, canary_qwen, moonshine, moonshine_streaming, moss, qwen3_asr, whisper). For whisper, a value containing cpu or all additionally prints the CPU sub-section breakdown.
TRANSCRIBE_VOXTRAL_REALTIME_STREAM_TIMING Print a per-component streaming wall-time breakdown at stream finalize (voxtral_realtime).
TRANSCRIBE_TEST_DEV_INIT_THROW=<match> Fault injection: backend device init (ggml_backend_dev_init) throws for devices whose name contains <match> (* matches every device). Exercises throw → skip → CPU-fallback in backend probing; an explicit backend request fails with TRANSCRIBE_ERR_BACKEND. Used by backend_init_throw_unit and scripts/ci/vulkan_degradation_check.py.
TRANSCRIBE_TEST_TEARDOWN_THROW Fault injection: any non-empty value injects a throw after each real free inside the transcribe::safe_* teardown wrappers, proving containment without leaking the handle. Used by teardown_safety_unit.

Tier 2 — validation hooks

Numerical-parity hooks for porting and validation. Compiled in only when the library is built with -DTRANSCRIBE_ENABLE_VALIDATION_HOOKS=ON (see the CMake option of the same name, or the validation preset). Release/wheel builds leave them out entirely — the env-var reads, ref-mel loaders, and dump scaffolding are all behind the compile guard, so these names do not even appear in a release binary. In a build without the flag, setting any of these has no effect; scripts/validate.py hard-fails --mel-from-ref against such a build rather than silently falling back.

Variable Effect
TRANSCRIBE_MEL_FROM_REF=<dir> Inject a reference log-mel from <dir> instead of computing it, so encoder drift can be isolated from frontend drift. Each family reads its own dump filename/layout from the directory (enc.mel.in.f32 for whisper / voxtral_realtime, frontend.mel.out.f32 for gigaam, mel.in.f32 for medasr). Driven by scripts/validate.py --mel-from-ref.
TRANSCRIBE_DUMP_ALL_BLOCKS Dump every encoder block output (not just mid/last) for a layer-by-layer divergence bisect (parakeet, gigaam). Requires TRANSCRIBE_DUMP_DIR.
TRANSCRIBE_DUMP_SUB_BLOCKS=<csv> Dump intermediate sub-layer activations (ff1/attn/conv/ff2) for the listed block indices, e.g. 0,12,23 (parakeet). Requires TRANSCRIBE_DUMP_DIR.

Build a validation-capable build/ with:

cmake --preset validation        # configures build/ with the hooks ON
cmake --build build --target transcribe-cli

When toggling TRANSCRIBE_ENABLE_VALIDATION_HOOKS on an existing build/, do a clean build of the target — an incremental build can leave a stale object that did not pick up the changed compile definition:

cmake --build build --clean-first --target transcribe-cli

(scripts/validate.py guards against the OFF case: it hard-fails --mel-from-ref when build/CMakeCache.txt has the flag off. Longer term, a dedicated validation build directory would avoid the toggle entirely.)

Test & tooling

Not part of the library runtime.

Real-model test model paths. Built only with -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON; each test skips (exit code 77) when its var is unset. Convention: TRANSCRIBE_<FAMILY>_GGUF.

Variable Test(s)
TRANSCRIBE_PARAKEET_GGUF parakeet_real_smoke, decoder_smoke
TRANSCRIBE_COHERE_GGUF cohere_real_smoke, cohere_e2e_smoke
TRANSCRIBE_WHISPER_GGUF whisper_e2e_smoke, whisper_tokenize_parity
TRANSCRIBE_QWEN3_ASR_GGUF (+ _0_6B_GGUF / _1_7B_GGUF) qwen3_asr smokes / parity
TRANSCRIBE_MOONSHINE_STREAMING_TINY_GGUF moonshine_streaming smokes
TRANSCRIBE_VOXTRAL_REALTIME_GGUF voxtral_realtime_real_smoke
TRANSCRIBE_WHISPER_BIN_* whisper.cpp .bin parser/e2e fixtures

Other test/tooling vars:

  • TRANSCRIBE_TEST_AUDIO — override the jfk.wav path for ad-hoc e2e runs.
  • TRANSCRIBE_TEST_SAMPLES_DIR / TRANSCRIBE_TEST_FIXTURES_DIR — sample and fixture directories, passed at configure time as compile definitions (not runtime env vars).
  • Python tooling: TRANSCRIBE_MODELS_DIR, TRANSCRIBE_DUMP_DIR (shared with the library), HF_TOKEN, and the binding-level TRANSCRIBE_BACKEND / TRANSCRIBE_LIBRARY. See tools/conversion.md and tools/validate.md.