python -m venv .venv
.venv/bin/pip install -e ".[dev]"The optional torch extra (CPU wheels are sufficient; nothing here uses a GPU) powers the trainable demos:
.venv/bin/pip install -e ".[dev,torch]" \
--extra-index-url https://download.pytorch.org/whl/cpuNumPy is the only required runtime dependency.
One work directory carries a run end to end; every stage reads what the previous stage wrote there.
echoscribe synth --workdir run --utterances 24 --seed 2025 # wav/ + manifest.jsonl
echoscribe feats --workdir run --num-mel-bins 40 # features.npz
echoscribe decode --workdir run --method greedy # decode.jsonl
echoscribe stream --workdir run --frames-per-chunk 16 # session.jsonl
echoscribe bias --workdir run --hotword "<unit>" # bias.jsonl
echoscribe eval --workdir run --level text --metric hybrid # scores.json
echoscribe bench --workdir run --repeats 3 # bench.json
echoscribe report --workdir run # report.svgechoscribe train --workdir run --method ctc trains a tiny model on a freshly
rendered laboratory (torch extra), and echoscribe demo --workdir run executes
the whole loop above in one call and prints the numbers it measured.
Exit codes: 0 success, 1 the job failed on valid usage (one line on
stderr), 2 the usage itself was wrong.
Two corpus-wide utilities round the pipeline out. echoscribe synth --noise-kind white --snr 5 renders every utterance with planted noise (the
manifest records the condition), and echoscribe denoise --workdir noisy --clean-workdir clean spectrally denoises a corpus -- measuring real SNR
improvement when given a clean render of the same seed, and refusing to
claim an SNR when it is not. echoscribe decode --confidences attaches
per-token posterior confidences to greedy fixture decodes.
Note what the default pipeline decodes: scripted fixture posteriors built from the planted transcripts. It exercises features, decoders, streaming, scoring and reporting against known answers; it does not run an acoustic model, and a zero error rate from it certifies the mechanics, not recognition.
The trained path runs through the same seam in the other direction:
echoscribe train --workdir run --method ctc --epochs 8 # model.pt + vocab.json
echoscribe decode --workdir run --bundle run/model.pt --out decode-bundle.jsonl
echoscribe eval --workdir run --decode-file decode-bundle.jsonltrain renders its own laboratory, trains a tiny encoder + CTC head, and
saves a versioned bundle plus the vocabulary the targets used. decode --bundle reloads both, produces real model posteriors through
echoscribe.model.infer, and scores like any other decode. One caveat is
printed with every bundle decode and repeated here: when train and decode see
the same laboratory, a low error rate is memorization of planted data,
not evidence of recognition. echoscribe demo --train runs the whole loop,
scripted and trained, side by side.
Features from a waveform:
from echoscribe import FeatureConfig, extract_log_mel, read_wav
audio = read_wav("utterance.wav")
log_mel = extract_log_mel(audio, FeatureConfig(num_mel_bins=40)) # (frames, 40)Decoding a posterior matrix:
from echoscribe.decode import ctc_greedy
from echoscribe.decode.posteriors import scripted_posteriors
posteriors = scripted_posteriors([3, 0, 1, 1, 0, 2], num_symbols=5)
greedy = ctc_greedy(posteriors)
greedy.symbols # (3, 1, 2): blanks dropped, repeats collapsedScoring a hypothesis against a reference:
from echoscribe.eval import format_summary, score_mixed, wer
format_summary(wer("the cat sat", "the cat"), label="WER")
# 'WER 33.33% | S0 D1 I0 | N3'
score_mixed("打开the document", "打开document") # hybrid, per-script attributionStreaming with a latency budget:
from echoscribe.stream import AppendableJoint, ChunkSchedule, StreamConfig, StreamDecoder
joint = AppendableJoint(num_symbols=5)
decoder = StreamDecoder(
joint, StreamConfig(schedule=ChunkSchedule(frames_per_chunk=16))
)
events = decoder.push_logits(logits_block) # partial hypotheses
events += decoder.finish() # the final
decoder.hypothesis.symbolsmake build, make test (fast suite), make test-all (adds slow and
model tests), make format, make lint, make typecheck, make release
and make demo mirror exactly what CI runs.
Every serialized artifact is JSON or JSONL with a schema version and a
round-trip test: corpus manifests (manifest.jsonl, checksummed wavs),
vocabularies, stream sessions (session.jsonl), stream recordings (base64
float64, digest-checked), bench results and model bundles (torch payloads
with config, state and history).
Two workflows guard the repository:
- CI runs on every push and pull request across Python 3.11, 3.12 and
3.13 on Ubuntu: install with the dev and torch extras (CPU wheel index
only), then
make build,make test-all,make format-check,make lintandmake typecheck-- the Makefile targets one for one, so "CI is green" and "make is green" are the same statement. - Release runs on
v*tags:make releasebuilds the sdist, the wheel andSHA256SUMS;scripts/check_package.pyinstalls the wheel into a throwaway venv and decodes through it;gh release createattaches the artifacts to the GitHub release. No package registry and no registry credentials are involved anywhere.
Dependabot watches pip and GitHub Actions monthly. torch updates are ignored by configuration: the CPU-only pin is a project invariant, not a version to chase.