v0.3.1

Added

• vkit show <pipeline.yaml>: pretty-print a pipeline as an operator
  chain with each stage's declarative field contract (reads / writes /
  optional_reads / clears) inline — same data the pre-flight uses,
  surfaced so users can see what a pipeline does without scanning raw
  YAML. Distinguishes "operator not importable here" from "operator
  declares no static contract" so the visualisation reads as
  intentional.
• vkit init now scaffolds a richer starter: data/.gitkeep so the
  directory survives git add, inline comments in the default
  pipeline.yaml explaining each stage and pointing at
  vkit operators for discovery, a step-numbered "Next steps"
  output that walks users through show → validate → docker run,
  and a README listing the full iteration loop including
  vkit card and vkit datasets.
• vkit validate --tag <image> (and vkit docker run) now run an
  op-vs-image pre-flight check: before launching a container they verify
  every operator in the pipeline is actually present in the target image,
  cross-checking the image's baked op_env_map.json. A pipeline that
  references an operator the image doesn't ship fails fast on the host with
  an actionable message instead of deep inside the container. Pass
  --no-preflight to skip.

Changed

• vkit inspect cuts: empty / directory paths now produce a friendly
  error with a hint instead of a Python traceback. Previously
  Path("") collapsed to Path(".") whose .exists() returned True
  but isn't a valid gzip stream, so the loader crashed.

• vkit validate: Pydantic config errors are rendered as a short
  bullet list rather than the raw errors.pydantic.dev multi-line
  dump; extra_forbidden rows get a did you mean hint via stdlib
  difflib when one of the operator's known fields is close enough
  (e.g. target_channel → target_channels).

• vkit doctor --expect now accepts image tags as well as env-group
  names: --expect slim is an alias for the core group, matching the
  published image tags users actually pull.

• vkit datasets: terminal browser for the dataset catalog — vkit datasets
  (filterable table; --task / --language / --recipe-only / --query compose),
  vkit datasets show <id> (Rich panel with all fields + download hint when
  recipe-backed), vkit datasets search <substring> (id/name/summary match).
  load_catalog() now skips the repo-relative pipeline existence check in
  installed (wheel) mode so the CLI works outside the source checkout.

• Weekly extras-ci GitHub Actions workflow that installs the heavy operator
  extras (asr / diarize / codec / tts-kokoro) the main ci workflow
  doesn't install, and runs the previously-SKIPPED tests against them. Surfaces
  upstream version drift like the encodec EncodedFrame change that previously
  hid for an unknown stretch. Matrix is fail-fast: false so one broken
  cluster doesn't block the others; also workflow_dispatch-triggerable.

• Four new ingest recipes (catalog count of recipe-backed datasets grows
  9 → 13): libritts_r (LibriTTS-R, en, CC BY 4.0), hifitts (Hi-Fi TTS,
  en multi-speaker, CC BY 4.0), thchs30 (THCHS-30, zh, Apache-2.0),
  thorsten_voice (Thorsten-Voice 2021.02 neutral, de, CC0-1.0). All four
  are now downloadable via vkit docker download <name> --root <dir> and
  parseable via vkit ingest --source recipe --recipe <name>. The matching
  catalog entries flip from manual to recipe-backed; the docs index now
  shows "Access: recipe" with the OpenSLR size range.

• vkit card <cuts.jsonl.gz>: generate a standalone, shareable HTML dataset
  card (quality distributions, language/gender breakdowns, metrics summary, and
  sample utterances) from a processed CutSet. Uses the viz extra.
  Pass --catalog-id <id> to auto-fill title, description, and a Source section
  (license, homepage, paper, recommendation) from voxkitchen/datasets/catalog.yaml.

• Third-party operator plugins: install a package exposing operators via the
  voxkitchen.operators entry-point group and they are discovered, listed by
  vkit operators / vkit doctor, and usable in pipelines. Added
  OPERATOR_API_VERSION, a plugin authoring guide, and an example package
  (examples/plugin-operator/).

• Dataset catalog (docs/datasets/): a decision-support catalog of speech
  datasets generated from voxkitchen/datasets/catalog.yaml, with per-dataset
  recommendations, access links, and (where available) a download recipe and a
  suggested processing pipeline. Searchable via the docs site; browse by task.
  Now 60 entries — added (most recent batch) VoxCeleb1, TIMIT, MGB-2 (Arabic),
  SEAME (zh-en code-switching), Earnings-21, MyST (children's speech), AVSpeech
  (audio-visual), Opencpop (zh singing), DiPCo (far-field), SLUE (spoken
  language understanding); previously THCHS-30, MagicData-RAMC, Shrutilipi,
  AISHELL-2, JSUT, Thorsten-Voice, LibriTTS-R, MELD, MSP-IMPROV, IMDA NSC.

• Declarative field contracts (reads/writes/optional_reads/clears) on
  every operator, making data-flow dependencies machine-readable.

• Static pre-flight validation in vkit validate and as a fail-fast gate before
  every vkit run / vkit docker run (and in --dry-run): broken operator
  chains — a stage requiring a field no upstream stage produces, or a
  quality_score_filter condition referencing an absent metric — are reported
  before the executor starts, not mid-run. Pass --no-preflight to vkit validate, vkit run, or vkit docker run (forwarded to the in-container
  run) to skip the check.

• normalize_text operator: strips model-specific markup (e.g. SenseVoice
  emotion/language tags) and collapses whitespace (e.g. Paraformer
  inter-character spaces) in ASR transcripts before downstream use.

• pack_jsonl now exports word_alignments when present on a cut.

• Simplified Chinese README (README.zh-CN.md), a full translation of
  the top-level README. The English and Chinese READMEs cross-link each
  other in the header; all deeper docs remain English-only.

• Both READMEs now show a collapsed "Example output" block under Quick
  Start with the actual vkit docker run + vkit inspect run logs for
  the bundled demo-no-asr pipeline.

• CITATION.cff and a "Citation" section in both READMEs, so GitHub
  renders a "Cite this repository" entry for research use.

• scripts/release.sh <version> --docker-only skips the tag + git push
  steps and goes straight to the Docker build/push loop. Useful when
  PyPI publish already succeeded from an earlier run (or from a
  different machine) and you only need to (re)build the GHCR images.
  Mutually exclusive with --replace-unpublished. Pre-flight CHANGELOG
  and CI checks still run because the Docker build bakes the current
  source into the image.

Changed

• Dropped the "Pre-alpha" status banner from the README and bumped the
  PyPI Development Status classifier from 2 - Pre-Alpha to
  4 - Beta to match the current v0.3.x surface.
• vkit run --dry-run (and vkit docker run --dry-run) clarifies its
  GPU reporting. The gpus: header line is now labelled (requested),
  and when any stage prefers the GPU executor the stage table is
  followed by a note that the Device column shows the preferred
  executor — gpu stages run on GPU when one is available and fall back
  to CPU otherwise. This removes the confusion where a gpu stage such
  as silero_vad appeared to require a GPU even though it runs fine on
  the CPU-only slim image.

Fixed

• tts-data-prep template now normalizes text and performs forced alignment as
  its documentation claims; previously it declared word-level alignment but ran
  neither step. The ASR stage no longer performs a redundant internal alignment
  pass.
• Capped numpy<2.3 in the dev optional-dependency group. numba
  (pulled in by librosa via the segment extra) supports numpy<=2.2,
  so a fresh pip install -e .[dev] on a host with a newer NumPy failed
  to import librosa and broke local test collection. The core
  numpy>=1.24 runtime bound is unchanged.
• utmos_score now produces real scores. The operator imported
  speechmos.utmos, a module speechmos has never shipped (it provides
  aecmos/dnsmos/plcmos only), so the import failed unconditionally. UTMOS22
  is now loaded via torch.hub from tarepan/SpeechMOS:v1.2.0, which needs
  only torch (present in every image, including slim).
• tts_cosyvoice default model_id is now iic/CosyVoice2-0.5B. The old
  default FunAudioLLM/CosyVoice2-0.5B was removed from ModelScope (404 on
  both endpoints), so the operator failed at setup for anyone relying on the
  default.
• tts_fish_speech no longer crashes with a dtype mismatch
  (Input type (float) and bias type (c10::BFloat16) should be the same).
  The float32 reference audio was fed to the bfloat16 DAC encoder; inference
  is now wrapped in torch.autocast so the cast happens automatically.
• TTS and forced-alignment operators no longer silently swallow per-cut
  failures. They previously caught their own exceptions and dropped the cut,
  hiding errors from the executor's per-cut fallback. Failures now propagate,
  are recorded to <stage>/_errors.jsonl, and trigger a warning when a stage
  drops 100% of its input cuts — so "pipeline complete, 0 cuts out" is no
  longer silent.
• read_cuts now warns when a manifest line is malformed or missing its
  __type__ marker instead of silently skipping it, so user-built manifests
  that produced "0 cuts in" now explain why.
• speechbrain_langid now writes a real language instead of None for every
  input. The VoxLingua107 model emits "<iso>: <name>" labels (e.g.
  "en: English"); the operator passed the raw label to normalize_language,
  which couldn't parse it, so the language field was always None. It now
  extracts the ISO code before normalizing.
• wenet_asr is now installed reliably and is part of the guaranteed asr
  image. wenet has no PyPI release and its repo's .gitmodules references a
  URL-less submodule, so the previous git+https install failed
  (git submodule update --init aborted) and the operator was silently
  absent. It's now cloned without submodules at a pinned commit and installed
  from the local checkout, with the asr constraint keeping torch at 2.4.1
  (newer torch dropped a private re-export wenet imports). The default model
  also moved from chinese to wenetspeech — wenet removed the
  chinese/english hub aliases, so the old default failed with
  train.yaml not found. (transcribe(engine="wenet") updated to match.)