Skip to content

Latest commit

 

History

History
151 lines (114 loc) · 5.72 KB

usage.md

File metadata and controls

151 lines (114 loc) · 5.72 KB

Usage

Installation

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/cpu

NumPy is the only required runtime dependency.

The command line

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.svg

echoscribe 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.jsonl

train 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.

The library

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 collapsed

Scoring 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 attribution

Streaming 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.symbols

Make targets

make 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.

File formats

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).

Continuous integration

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 lint and make 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 release builds the sdist, the wheel and SHA256SUMS; scripts/check_package.py installs the wheel into a throwaway venv and decodes through it; gh release create attaches 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.