From 07dc462c632ea0610f0fd236ef323c5591803de5 Mon Sep 17 00:00:00 2001 From: Praveen Perera Date: Thu, 5 Nov 2026 16:11:25 -0600 Subject: [PATCH 1/4] Silence dead code in builds with no backend A Linux build without the cuda feature has no backend, so the chunk, policy and decode helpers that only a backend reads are unused there. Allow dead code for exactly that configuration, so consumers of the packaged crate build cleanly under -D warnings in every feature set. --- src/backend.rs | 8 ++++++++ src/backend/policy.rs | 8 ++++++++ src/constants.rs | 4 ++++ src/decode.rs | 7 +++++++ 4 files changed, 27 insertions(+) diff --git a/src/backend.rs b/src/backend.rs index 8f776ae..7c4bd67 100644 --- a/src/backend.rs +++ b/src/backend.rs @@ -25,10 +25,18 @@ pub(crate) use policy::test_support::decide_from_logits; /// Log-mel input for one chunk, in `[frames, features]` order #[derive(Debug, Clone, Copy)] +#[cfg_attr( + not(any(target_os = "macos", feature = "cuda")), + allow(dead_code, reason = "a build with no backend never runs a chunk") +)] pub(crate) struct EncoderChunk<'a> { features: ArrayView2<'a, f32>, } +#[cfg_attr( + not(any(target_os = "macos", feature = "cuda")), + allow(dead_code, reason = "a build with no backend never runs a chunk") +)] impl<'a> EncoderChunk<'a> { pub(crate) fn new(features: ArrayView2<'a, f32>) -> Self { Self { features } diff --git a/src/backend/policy.rs b/src/backend/policy.rs index f89e9bb..57f62e2 100644 --- a/src/backend/policy.rs +++ b/src/backend/policy.rs @@ -18,6 +18,10 @@ pub(crate) struct DecodePolicy<'a> { deployment: &'a ParakeetDeployment, vocabulary: &'a Vocabulary, language: LanguageSelection, + #[cfg_attr( + not(any(target_os = "macos", feature = "cuda")), + allow(dead_code, reason = "only a backend decodes with the policy") + )] keep_top_k: bool, } @@ -57,6 +61,10 @@ impl<'a> DecodePolicy<'a> { MAX_TOKENS_PER_STEP } + #[cfg_attr( + not(any(target_os = "macos", feature = "cuda")), + allow(dead_code, reason = "only a backend decodes with the policy") + )] pub(crate) fn keep_top_k(&self) -> bool { self.keep_top_k } diff --git a/src/constants.rs b/src/constants.rs index 5dacf27..b034326 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -15,6 +15,10 @@ pub(crate) const SECONDS_PER_ENCODER_FRAME: f64 = pub(crate) const ENCODER_HIDDEN_SIZE: usize = 1_024; pub(crate) const DECODER_HIDDEN_SIZE: usize = 640; pub(crate) const DECODER_LAYERS: usize = 2; +#[cfg_attr( + not(any(target_os = "macos", feature = "cuda")), + allow(dead_code, reason = "only a backend decodes") +)] pub(crate) const MAX_TOKENS_PER_STEP: usize = 10; // width of the v3 joint's top-K outputs in the published Core ML bundle; device // backends filter languages over the same candidate set diff --git a/src/decode.rs b/src/decode.rs index 5cfa767..726dc12 100644 --- a/src/decode.rs +++ b/src/decode.rs @@ -20,6 +20,13 @@ pub(crate) struct RawTranscription { } impl RawTranscription { + #[cfg_attr( + not(any(target_os = "macos", feature = "cuda", feature = "long-form")), + allow( + dead_code, + reason = "only a backend or the long-form merge starts an empty transcription" + ) + )] pub(crate) fn empty() -> Self { Self { tokens: Vec::new() } } From 3a01d848a4061529c4b858e4d9a2f83b0ed474dd Mon Sep 17 00:00:00 2001 From: Praveen Perera Date: Thu, 5 Nov 2026 16:11:31 -0600 Subject: [PATCH 2/4] Format and lint the Python package with ruff Apply ruff's formatter and its autofixes for Python 3.11+, such as X | None in place of Optional, so CI can check both from here on. --- crates/scriptrs-python/pyproject.toml | 6 ++++++ .../python/scriptrs/__init__.py | 21 ++++++++----------- .../python/scriptrs/_native.pyi | 15 +++++++------ crates/scriptrs-python/python/scriptrs/cli.py | 18 +++++++--------- 4 files changed, 29 insertions(+), 31 deletions(-) diff --git a/crates/scriptrs-python/pyproject.toml b/crates/scriptrs-python/pyproject.toml index 108161c..5aa636c 100644 --- a/crates/scriptrs-python/pyproject.toml +++ b/crates/scriptrs-python/pyproject.toml @@ -52,3 +52,9 @@ features = ["pyo3/extension-module"] [tool.pytest.ini_options] testpaths = ["tests"] markers = ["model: loads a Parakeet model, so it needs a backend and downloads the model"] + +[tool.ruff] +line-length = 120 + +[tool.ruff.lint.isort] +known-first-party = ["scriptrs", "conftest"] diff --git a/crates/scriptrs-python/python/scriptrs/__init__.py b/crates/scriptrs-python/python/scriptrs/__init__.py index fe64fbd..7b1ea71 100644 --- a/crates/scriptrs-python/python/scriptrs/__init__.py +++ b/crates/scriptrs-python/python/scriptrs/__init__.py @@ -15,11 +15,12 @@ from __future__ import annotations +from collections.abc import Sequence from enum import Enum from importlib import metadata from os import PathLike from pathlib import Path -from typing import TYPE_CHECKING, Literal, Optional, Sequence, Union +from typing import TYPE_CHECKING, Literal from . import _cuda, _native from ._errors import ScriptrsError @@ -42,7 +43,7 @@ class _ArrayInterface(Protocol): @property def __array_interface__(self) -> dict[str, Any]: ... - Samples = Union[Buffer, _ArrayInterface, Sequence[float]] + Samples = Buffer | _ArrayInterface | Sequence[float] try: __version__ = metadata.version("scriptrs") @@ -70,7 +71,7 @@ def languages(self) -> list[str]: return _native.languages(self.value) -ModelName = Union[Model, Literal["parakeet/v2", "parakeet/v3"], str] +ModelName = Model | Literal["parakeet/v2", "parakeet/v3"] | str """A :class:`Model`, its value, or its upstream model id.""" Precision = Literal["fp16", "tf32", "fp32"] @@ -80,7 +81,7 @@ def languages(self) -> list[str]: and ``"fp32"`` matches NVIDIA NeMo's FP32 output token for token. """ -StrPath = Union[str, "PathLike[str]"] +StrPath = str | PathLike[str] # upstream model ids, so a name copied from Hugging Face or NeMo works as is _UPSTREAM_IDS = { @@ -127,7 +128,7 @@ def from_pretrained( *, vad: bool = False, precision: Precision = "fp16", - cache_dir: Optional[StrPath] = None, + cache_dir: StrPath | None = None, ) -> Pipeline: """Download ``model`` from Hugging Face if needed, then load it. @@ -195,9 +196,7 @@ def max_chunk_seconds(self) -> float: """ return self._native.max_chunk_seconds - def transcribe( - self, samples: Samples, *, language: Optional[str] = None - ) -> TranscriptionResult: + def transcribe(self, samples: Samples, *, language: str | None = None) -> TranscriptionResult: """Transcribe 16 kHz mono audio. ``samples`` is a 1-D float32 buffer, such as a NumPy array, or a sequence @@ -207,9 +206,7 @@ def transcribe( """ return self._native.transcribe(samples, language) - def transcribe_file( - self, path: StrPath, *, language: Optional[str] = None - ) -> TranscriptionResult: + def transcribe_file(self, path: StrPath, *, language: str | None = None) -> TranscriptionResult: """Decode an audio file, resample it to 16 kHz mono, and transcribe it. WAV, FLAC, MP3, Ogg Vorbis, and AAC in MP4/M4A are supported. The whole @@ -221,7 +218,7 @@ def transcribe_many( self, inputs: Sequence[Samples], *, - language: Optional[str] = None, + language: str | None = None, max_batch: int = 32, ) -> list[TranscriptionResult]: """Transcribe many 16 kHz mono clips faster than calling :meth:`transcribe` in a loop. diff --git a/crates/scriptrs-python/python/scriptrs/_native.pyi b/crates/scriptrs-python/python/scriptrs/_native.pyi index 24035da..bee16fb 100644 --- a/crates/scriptrs-python/python/scriptrs/_native.pyi +++ b/crates/scriptrs-python/python/scriptrs/_native.pyi @@ -1,7 +1,8 @@ +from collections.abc import Sequence from pathlib import Path -from typing import Any, Optional, Sequence, final +from typing import Any, final -BACKEND: Optional[str] +BACKEND: str | None """Backend compiled into this build: ``"coreml"``, ``"cuda"``, or ``None``.""" ALL_LANGUAGES: list[str] """ISO 639-1 codes of every language a model transcribes.""" @@ -69,13 +70,11 @@ class _Pipeline: def languages(self) -> list[str]: ... @property def max_chunk_seconds(self) -> float: ... - def transcribe(self, samples: Any, language: Optional[str] = None) -> TranscriptionResult: ... - def transcribe_file(self, path: Path, language: Optional[str] = None) -> TranscriptionResult: ... + def transcribe(self, samples: Any, language: str | None = None) -> TranscriptionResult: ... + def transcribe_file(self, path: Path, language: str | None = None) -> TranscriptionResult: ... def transcribe_many( - self, inputs: Sequence[Any], language: Optional[str] = None, max_batch: int = 32 + self, inputs: Sequence[Any], language: str | None = None, max_batch: int = 32 ) -> list[TranscriptionResult]: ... -def _from_pretrained( - model: str, vad: bool, precision: str, cache_dir: Optional[Path] = None -) -> _Pipeline: ... +def _from_pretrained(model: str, vad: bool, precision: str, cache_dir: Path | None = None) -> _Pipeline: ... def _from_dir(path: Path, model: str, vad: bool, precision: str) -> _Pipeline: ... diff --git a/crates/scriptrs-python/python/scriptrs/cli.py b/crates/scriptrs-python/python/scriptrs/cli.py index a4da26c..fa6d8e1 100644 --- a/crates/scriptrs-python/python/scriptrs/cli.py +++ b/crates/scriptrs-python/python/scriptrs/cli.py @@ -5,17 +5,15 @@ import argparse import json import sys +from collections.abc import Sequence from pathlib import Path -from typing import Sequence from . import Model, Pipeline, ScriptrsError, TranscriptionResult, __version__ def main(argv: Sequence[str] | None = None) -> int: """Run the command line and return the exit status.""" - parser = argparse.ArgumentParser( - prog="scriptrs", description="Speech-to-text with NVIDIA Parakeet TDT." - ) + parser = argparse.ArgumentParser(prog="scriptrs", description="Speech-to-text with NVIDIA Parakeet TDT.") parser.add_argument("--version", action="version", version=f"scriptrs {__version__}") commands = parser.add_subparsers(dest="command", required=True) @@ -42,7 +40,9 @@ def main(argv: Sequence[str] | None = None) -> int: choices=["fp16", "tf32", "fp32"], help="CUDA matrix multiply precision (default: fp16)", ) - transcribe.add_argument("--model-dir", type=Path, help="load the model from this directory instead of downloading it") + transcribe.add_argument( + "--model-dir", type=Path, help="load the model from this directory instead of downloading it" + ) transcribe.add_argument("--cache-dir", type=Path, help="model download cache (default: the Hugging Face hub cache)") transcribe.add_argument( "--json", @@ -53,9 +53,7 @@ def main(argv: Sequence[str] | None = None) -> int: try: if args.model_dir is not None: - pipeline = Pipeline.from_dir( - args.model_dir, args.model, vad=args.vad, precision=args.precision - ) + pipeline = Pipeline.from_dir(args.model_dir, args.model, vad=args.vad, precision=args.precision) else: pipeline = Pipeline.from_pretrained( args.model, vad=args.vad, precision=args.precision, cache_dir=args.cache_dir @@ -88,9 +86,7 @@ def _as_json(path: Path, result: TranscriptionResult) -> dict[str, object]: "file": str(path), "text": result.text, "duration_seconds": result.duration_seconds, - "chunks": [ - {"start": chunk.start, "end": chunk.end, "text": chunk.text} for chunk in result.chunks - ], + "chunks": [{"start": chunk.start, "end": chunk.end, "text": chunk.text} for chunk in result.chunks], "tokens": [ { "text": token.text, From 0f0b467e3576646f81e943328823e507ede551d7 Mon Sep 17 00:00:00 2001 From: Praveen Perera Date: Thu, 5 Nov 2026 16:11:31 -0600 Subject: [PATCH 3/4] Add release checks and publish from version tags Bring CI in line with speakrs and sam3rs before the first PyPI release. Pull requests now run cargo-deny, ruff, a docs.rs-style doc build, and a packaging check that builds the packaged crate as a dependency with each feature set, and the wheel tests run on Python 3.11 and 3.14. A v* tag checks the version and its CHANGELOG.md entry, publishes to TestPyPI and installs it, then after review publishes to PyPI and crates.io and creates a GitHub release with the wheels and sdist. Every step can be rerun without touching what is already published. --- .github/workflows/ci.yml | 21 ++- .github/workflows/python.yml | 193 +++++++++++++++++++++++++- CHANGELOG.md | 71 ++++++++++ Cargo.toml | 5 + README.md | 1 + crates/scriptrs-python/pyproject.toml | 1 + deny.toml | 32 +++++ justfile | 70 ++++++++++ 8 files changed, 386 insertions(+), 8 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 deny.toml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4fb51b6..93dad0a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,10 +35,16 @@ jobs: toolchain: stable components: rustfmt - - name: Install just + # a prebuilt cargo-deny instead of cargo-deny-action, whose Docker build fails + # whenever Docker Hub rate-limits the runner + - name: Install just and cargo-deny uses: taiki-e/install-action@86f7a0ffb25f40114606501a311ebcfaf882ea32 # v2.88.0 with: - tool: just + tool: just,cargo-deny@0.20.2 + + # `just fmt` and `just python-lint` run ruff through uvx + - name: Install uv + uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0 # `just fmt` rewrites files, so any diff it leaves means the code wasn't formatted - name: Format @@ -46,9 +52,15 @@ jobs: just fmt git diff --exit-code + - name: Python lints + run: just python-lint + - name: No ONNX Runtime run: just no-ort + - name: Advisories, licenses and sources + run: just deny + check: name: Clippy and tests (${{ matrix.name }}) runs-on: ${{ matrix.os }} @@ -81,5 +93,10 @@ jobs: - name: Clippy run: just clippy + # docs.rs builds on Linux with every feature, so the CUDA docs only build here + - name: Docs as docs.rs builds them + if: runner.os == 'Linux' + run: just doc + - name: Test run: just test --all-features diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index a6f1a9a..20f00f9 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -1,3 +1,22 @@ +# Build, test and publish scriptrs: the Python wheels and sdist, the crate, and a +# GitHub release, all from one version tag +# +# To release: +# 1. set the version in Cargo.toml and crates/scriptrs-python/Cargo.toml +# 2. rename the CHANGELOG.md "Unreleased" section to "[X.Y.Z] - YYYY-MM-DD" and +# update the compare links at the bottom +# 3. merge, then tag the merge commit and push the tag: +# git tag vX.Y.Z +# git push origin vX.Y.Z +# +# The tag publishes to TestPyPI and installs that release. The pypi environment then +# waits for a reviewer, and once approved the workflow publishes the Python package to +# PyPI, then the crate to crates.io, then a GitHub release with the tag's CHANGELOG.md +# entry as its notes and the wheels and sdist attached. A tag whose version or +# changelog entry is wrong fails before anything is published. PyPI, TestPyPI and +# crates.io all trust this workflow through OIDC, so no token is stored. Every publish +# skips files already uploaded, so "Re-run failed jobs" finishes a partial release + name: Python on: @@ -19,6 +38,28 @@ env: RUSTFLAGS: -D warnings jobs: + # the crate as crates.io receives it, built as a dependency with each feature set + crate: + name: Crate + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v6 + + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + with: + toolchain: stable + + - name: Install just + uses: taiki-e/install-action@86f7a0ffb25f40114606501a311ebcfaf882ea32 # v2.88.0 + with: + tool: just + + - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Package and build as a dependency + run: just package + # one abi3 wheel per platform with the backend that platform runs; the Linux # wheel builds without a GPU or CUDA toolkit because CUDA is loaded at run time wheels: @@ -118,13 +159,13 @@ jobs: path: dist/*.tar.gz tests: - name: Tests (${{ matrix.name }}) + name: Tests (${{ matrix.platform.name }}, Python ${{ matrix.python }}) needs: wheels - runs-on: ${{ matrix.os }} + runs-on: ${{ matrix.platform.os }} strategy: fail-fast: false matrix: - include: + platform: # a GitHub runner has no NVIDIA driver, so this checks that the CUDA wheel # imports and fails cleanly before downloading a model - name: Linux x86_64 @@ -134,6 +175,8 @@ jobs: - name: macOS arm64 os: macos-15 target: aarch64-apple-darwin + # the one abi3 wheel serves every version, so test the oldest and the newest + python: ["3.11", "3.14"] env: SCRIPTRS_TEST_MODELS: parakeet/v2 steps: @@ -145,26 +188,58 @@ jobs: - name: Download wheel uses: actions/download-artifact@v8 with: - name: python-wheel-${{ matrix.target }} + name: python-wheel-${{ matrix.platform.target }} path: dist - name: Install wheel into a fresh environment shell: bash run: | set -euo pipefail - uv venv --python 3.12 .venv-wheel + uv venv --python ${{ matrix.python }} .venv-wheel uv pip install --python .venv-wheel dist/*.whl pytest numpy - name: Run tests working-directory: crates/scriptrs-python run: ../../.venv-wheel/bin/python -m pytest -rA + # checks a tag before anything is published: the crate's version must match it, and + # CHANGELOG.md needs its entry, which becomes the GitHub release notes + release-check: + name: Check the tag + if: startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v6 + + # the GitHub release reads its notes with parse-changelog, so the same parser + # checks the entry here + - name: Install parse-changelog + uses: taiki-e/install-action@86f7a0ffb25f40114606501a311ebcfaf882ea32 # v2.88.0 + with: + tool: parse-changelog + + - name: Check the version and changelog + shell: bash + run: | + set -euo pipefail + version="${GITHUB_REF_NAME#v}" + crate=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1) + if [ "$crate" != "$version" ]; then + echo "Cargo.toml is $crate but the tag is $GITHUB_REF_NAME" + exit 1 + fi + notes="$(parse-changelog CHANGELOG.md "$version")" + if [ -z "$notes" ]; then + echo "the CHANGELOG.md entry for $version is empty" + exit 1 + fi + # a v* tag publishes to TestPyPI, installs that release, and only then publishes to # PyPI; each index trusts this workflow and environment, so no token is stored testpypi-publish: name: Publish to TestPyPI if: startsWith(github.ref, 'refs/tags/v') - needs: [wheels, sdist, tests] + needs: [release-check, crate, wheels, sdist, tests] runs-on: ubuntu-24.04 environment: name: testpypi @@ -197,6 +272,7 @@ jobs: uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 with: repository-url: https://test.pypi.org/legacy/ + skip-existing: true testpypi-install: name: Install from TestPyPI (${{ matrix.name }}) @@ -241,6 +317,8 @@ jobs: grep -qi 'indifference' <<< "$text" fi + # the pypi environment's reviewer approves the release here, before anything + # outside TestPyPI is published pypi-publish: name: Publish to PyPI needs: testpypi-install @@ -260,3 +338,106 @@ jobs: - name: Publish uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 + with: + skip-existing: true + + crates-publish: + name: Publish to crates.io + needs: pypi-publish + runs-on: ubuntu-24.04 + environment: + name: crates-io + url: https://crates.io/crates/scriptrs + permissions: + id-token: write + steps: + - uses: actions/checkout@v6 + + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + with: + toolchain: stable + + # a rerun after a later job failed finds this version already published + - name: Check crates.io for this version + id: version + shell: bash + run: | + set -euo pipefail + version="${GITHUB_REF_NAME#v}" + status="$(curl -sS -o /dev/null -w '%{http_code}' -A 'scriptrs-release (github.com/avencera/scriptrs)' \ + "https://crates.io/api/v1/crates/scriptrs/$version")" + case "$status" in + 200) echo "scriptrs $version is already on crates.io"; echo "publish=false" >> "$GITHUB_OUTPUT" ;; + 404) echo "publish=true" >> "$GITHUB_OUTPUT" ;; + *) echo "crates.io answered HTTP $status" >&2; exit 1 ;; + esac + + - name: Get a crates.io token + if: steps.version.outputs.publish == 'true' + id: auth + uses: rust-lang/crates-io-auth-action@3268eb413133e2960fa4ae0e963ca76380c54cd9 # v1.0.6 + + - name: Publish + if: steps.version.outputs.publish == 'true' + env: + CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }} + run: cargo publish --locked -p scriptrs + + # the release starts as a draft and is published only once its files are attached + github-release: + name: GitHub release + needs: crates-publish + runs-on: ubuntu-24.04 + permissions: + contents: write + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + + - name: Download wheels and sdist + uses: actions/download-artifact@v8 + with: + pattern: python-* + path: dist + merge-multiple: true + + # create-gh-release-action deletes a release that already exists, so a rerun + # leaves a published release alone and finishes a draft instead of recreating it + - name: Check for an existing release + id: existing + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + shell: bash + run: | + set -euo pipefail + if draft="$(gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --json isDraft --jq .isDraft 2> view.err)"; then + if [ "$draft" = true ]; then state=draft; else state=published; fi + elif grep -q 'release not found' view.err; then + state=none + else + # any other failure could hide a release the next step would delete + cat view.err >&2 + exit 1 + fi + echo "the $GITHUB_REF_NAME release is $state" + echo "state=$state" >> "$GITHUB_OUTPUT" + + - name: Create a draft release + if: steps.existing.outputs.state == 'none' + uses: taiki-e/create-gh-release-action@eba8ea96c86cca8a37f1b56e94b4d13301fba651 # v1.11.0 + with: + draft: true + # the tag's CHANGELOG.md entry becomes the release notes + changelog: CHANGELOG.md + + # --clobber replaces files a failed run already attached + - name: Attach the wheels and sdist, then publish + if: steps.existing.outputs.state != 'published' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -euo pipefail + gh release upload "$GITHUB_REF_NAME" dist/* --clobber --repo "$GITHUB_REPOSITORY" + gh release edit "$GITHUB_REF_NAME" --draft=false --latest --repo "$GITHUB_REPOSITORY" diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..40d06bd --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,71 @@ +# Changelog + +All notable changes to scriptrs and its Python package are listed here. The format +follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow +[Semantic Versioning](https://semver.org/). The Rust crate and the Python package share +one version. + +## [Unreleased] + +The first release on PyPI. It has breaking changes to the Rust API; the README's +"Breaking changes in 0.5.0" section lists what to write instead. + +### Added + +- Python package `scriptrs` on PyPI, with one wheel for every Python version from 3.11: + Core ML on macOS arm64 and CUDA on Linux x86_64. It includes the `scriptrs transcribe` + command. +- `TranscriptionScheduler` batches windows across concurrent requests on CUDA, for + servers with many short requests. `SchedulerConfig::max_requests` bounds the requests + held at once, and `try_submit` returns `TranscriptionError::SchedulerFull` past it. +- Silero VAD 6.2.3. VAD mode now scores each window with both 5.1.2 and 6.2.3, keeps + the higher speech probability, and uses a 0.6 threshold. `VadModel::SileroV5` and + `VadModel::SileroV6` run one model alone at 0.5. +- VAD mode transcribes each speech region as soon as the scan passes it, which makes + it 13 to 36% faster on the benchmark sets with identical transcripts. +- Interrupted model downloads resume where they stopped, and concurrent downloads of + one file wait for each other through the same lock file as `huggingface_hub`. + +### Changed + +- `TranscriptionConfig` has only `language`. The frontend settings and the input limit + come from the model bundle. `from_deployment` and `validate_for` are gone. +- `TranscriptionError::Control` wraps `TranscriptionControlError` in place of the three + variants that mirrored it. Messages and Python error codes are unchanged. +- `Vocabulary` loads only through a deployment, with `Vocabulary::load` or + `Vocabulary::from_bytes`. `VocabKind` is gone. +- `VadConfig` is gone. The threshold is `VadSegmentationConfig::threshold`. +- Hub downloads go through [hf-fetch](https://crates.io/crates/hf-fetch). Download + errors leave out the signed query of storage URLs. +- In Python, `transcribe_many` submits every clip before waiting, its `max_batch` + default is 32, and the error code `queue` is now `scheduler`. + +### Fixed + +- Long-form VAD timestamps could be up to 80 ms early in the overlap fallback. +- Clips from 30 to 40 s on native CUDA bundles ran as one window and skipped VAD. +- A failed long-form run cancelled the caller's `TranscriptionControl`. +- A Core ML encoder length of 0 decoded padding as speech. +- Core ML inputs and the FP8 and NVFP4 cuBLASLt buffers are checked before use, in + place of reads that could go out of bounds. +- A streaming checkpoint with no left attention context panicked instead of failing + to load. +- A failing Silero scan or worker thread now stops the whole run promptly. + +## [0.4.0] - 2026-10-30 + +### Added + +- Python bindings, built as wheels for macOS arm64 and Linux x86_64. +- Cache-aware streaming transcription on CUDA with `StreamingModel`. +- FP8, INT8 and NVFP4 encoder precisions behind the `low-precision` feature. +- Native CUDA weights download from one Hugging Face repository per model. + +### Changed + +- `Precision` is `#[non_exhaustive]`. +- VAD regions are padded by 0.2 s so soft first words are kept. +- The relative-position attention runs as one fused kernel on CUDA. + +[Unreleased]: https://github.com/avencera/scriptrs/compare/v0.4.0...HEAD +[0.4.0]: https://github.com/avencera/scriptrs/releases/tag/v0.4.0 diff --git a/Cargo.toml b/Cargo.toml index 032a4bd..4a8a19a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,6 +14,11 @@ readme = "README.md" keywords = ["parakeet", "speech-to-text", "asr", "cuda", "coreml"] categories = ["multimedia::audio"] +# the crate docs link the long-form, VAD and CUDA items, so docs.rs documents every +# feature; the CUDA code builds without a toolkit because CUDA loads at run time +[package.metadata.docs.rs] +all-features = true + [features] default = ["online"] # blocking Hub downloads through hf-fetch, with rustls and no async runtime diff --git a/README.md b/README.md index daf6f56..16ef0ea 100644 --- a/README.md +++ b/README.md @@ -730,6 +730,7 @@ The example expects mono 16kHz WAV input. ## Notes +- [CHANGELOG.md](CHANGELOG.md) lists the changes in each release - The public API is still moving - `scriptrs` currently targets the exact file layout and model I/O shipped in `avencera/scriptrs-models`; if you swap in a different CoreML Parakeet export, you may need runtime code changes - Use `long-form` for the fastest path on clean, dense speech diff --git a/crates/scriptrs-python/pyproject.toml b/crates/scriptrs-python/pyproject.toml index 5aa636c..e98272d 100644 --- a/crates/scriptrs-python/pyproject.toml +++ b/crates/scriptrs-python/pyproject.toml @@ -40,6 +40,7 @@ scriptrs = "scriptrs.cli:main" [project.urls] Repository = "https://github.com/avencera/scriptrs" Documentation = "https://github.com/avencera/scriptrs/blob/master/crates/scriptrs-python/README.md" +Changelog = "https://github.com/avencera/scriptrs/blob/master/CHANGELOG.md" [dependency-groups] test = ["pytest>=8", "numpy>=1.26"] diff --git a/deny.toml b/deny.toml new file mode 100644 index 0000000..02e5072 --- /dev/null +++ b/deny.toml @@ -0,0 +1,32 @@ +[advisories] +version = 2 +yanked = "deny" + +[licenses] +version = 2 +confidence-threshold = 0.8 +# one policy covers the crate and the Python bindings, which use different licenses +unused-allowed-license = "allow" +allow = [ + "Apache-2.0", + # pyo3-build-config depends on target-lexicon + "Apache-2.0 WITH LLVM-exception", + "BSD-3-Clause", + "ISC", + "MIT", + # symphonia, which the Python bindings decode audio with + "MPL-2.0", + "Unicode-3.0", + "Zlib", + "CDLA-Permissive-2.0", +] + +[bans] +multiple-versions = "allow" +wildcards = "allow" +highlight = "all" + +[sources] +unknown-registry = "deny" +unknown-git = "deny" +allow-registry = ["https://github.com/rust-lang/crates.io-index"] diff --git a/justfile b/justfile index ee6272c..8dd6e29 100644 --- a/justfile +++ b/justfile @@ -1,6 +1,22 @@ fmt: cargo fmt cargo fmt --manifest-path crates/scriptrs-python/Cargo.toml + uvx ruff@0.17.4 format crates/scriptrs-python + +# ruff's lints for the Python package; `just fmt` runs its formatter. ruff is pinned +# because a release that restyles code would fail CI's formatting check +python-lint: + uvx ruff@0.17.4 check crates/scriptrs-python + +# advisories, licenses and sources for the crate and the Python bindings, which are +# separate workspaces +deny: + cargo deny --all-features check + cargo deny --manifest-path crates/scriptrs-python/Cargo.toml --all-features check + +# the docs as docs.rs builds them, with every feature +doc: + DOCS_RS=1 RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked --all-features clippy: cargo clippy --all --all-targets --all-features -- -D warnings @@ -19,6 +35,57 @@ no-ort: deps=$(cargo tree --all-features --target all -e normal,build --prefix none) if grep -qE '^ort(-sys)? ' <<<"$deps"; then echo "ort is in the dependency tree" >&2; exit 1; fi +# package the crate as crates.io receives it, check its size, and build consumers of +# the unpacked archive, so a file left out of the package fails here instead of after +# publishing; the CUDA consumer checks the committed PTX ships, on Linux x86_64 only +package *args: + #!/usr/bin/env bash + set -euo pipefail + rm -rf target/package + cargo package --locked {{args}} + crate=$(find target/package -maxdepth 1 -name 'scriptrs-*.crate' -print -quit) + test -n "$crate" + # crates.io rejects uploads over 10 MiB unless it raises the crate's limit + size=$(wc -c < "$crate") + echo "$(basename "$crate"): $size bytes" + test "$size" -le $((10 * 1024 * 1024)) + + work=$(mktemp -d) + trap 'rm -rf "$work"' EXIT + tar -xzf "$crate" -C "$work" + package=$(find "$work" -mindepth 1 -maxdepth 1 -type d -print -quit) + # each consumer is its own workspace in a new directory, so keep its build files + # in this target too rather than in a fresh build directory per run + export CARGO_TARGET_DIR="$PWD/target/package-consumers" + export CARGO_BUILD_BUILD_DIR="$CARGO_TARGET_DIR/build" + + consumer() { + local name=$1 dependency=$2 source=$3 + mkdir -p "$work/$name/src" + printf '[package]\nname = "consumer-%s"\nversion = "0.0.0"\nedition = "2024"\npublish = false\n\n[workspace]\n\n[dependencies]\nscriptrs = %s\n' \ + "$name" "$dependency" > "$work/$name/Cargo.toml" + printf '%s\n' "$source" > "$work/$name/src/lib.rs" + echo "building the packaged crate as a dependency: $name" + cargo build --manifest-path "$work/$name/Cargo.toml" + } + + load='pub fn load(dir: &std::path::Path) -> bool { + scriptrs::TranscriptionPipeline::from_dir(dir).is_ok() + }' + consumer offline "{ path = \"$package\", default-features = false }" "$load" + consumer online "{ path = \"$package\" }" "$load + pub fn download() -> bool { + scriptrs::TranscriptionPipeline::from_pretrained().is_ok() + }" + consumer vad "{ path = \"$package\", features = [\"vad\"] }" 'pub fn load(dir: &std::path::Path) -> bool { + scriptrs::LongFormTranscriptionPipeline::from_dir(dir).is_ok() + }' + if [ "$(uname -s)-$(uname -m)" = Linux-x86_64 ]; then + consumer cuda "{ path = \"$package\", features = [\"cuda\", \"vad\"] }" 'pub fn download() -> bool { + scriptrs::ModelBundle::from_pretrained_native(scriptrs::ParakeetDeployment::v3()).is_ok() + }' + fi + # parity tests against NeMo reference tensors (dev-tools/nemo/dump_ref.py); # set SCRIPTRS_NEMO_REF to use a copy other than /shared/datasets/parakeet-ref parity *args: @@ -26,8 +93,11 @@ parity *args: check: just fmt + just python-lint just no-ort + just deny just clippy + just doc just test # GPU tests (`gpu_` prefix): NeMo parity and the scheduler; they need the GPU, so From a7d783e57d6421dbeb347838281ab4135f4ab776 Mon Sep 17 00:00:00 2001 From: Praveen Perera Date: Thu, 5 Nov 2026 19:37:03 -0600 Subject: [PATCH 4/4] Keep older releases from becoming latest Publishing a patch for an older line, such as 0.5.1 after 0.6.0, marked it as the repository's latest release. Mark a release latest only when no published stable release has a higher version. The package recipe looked for the archive under ./target, which fails when CARGO_TARGET_DIR or build.target-dir moves Cargo's target directory. Use the effective target directory instead. --- .github/workflows/python.yml | 22 ++++++++++++++++++++-- justfile | 9 ++++++--- 2 files changed, 26 insertions(+), 5 deletions(-) diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index 20f00f9..5df0fd7 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -432,12 +432,30 @@ jobs: # the tag's CHANGELOG.md entry becomes the release notes changelog: CHANGELOG.md - # --clobber replaces files a failed run already attached + # --clobber replaces files a failed run already attached. The release becomes + # latest only when no published stable release has a higher version, so a + # maintenance release of an older line leaves the newest one as latest - name: Attach the wheels and sdist, then publish if: steps.existing.outputs.state != 'published' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + shell: bash run: | set -euo pipefail gh release upload "$GITHUB_REF_NAME" dist/* --clobber --repo "$GITHUB_REPOSITORY" - gh release edit "$GITHUB_REF_NAME" --draft=false --latest --repo "$GITHUB_REPOSITORY" + + version="${GITHUB_REF_NAME#v}" + latest=false + if [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + # a plain assignment, so set -e stops the step when the lookup fails + # instead of marking this release latest against an empty list + releases="$(gh release list --repo "$GITHUB_REPOSITORY" --exclude-drafts --exclude-pre-releases \ + --limit 1000 --json tagName --jq '.[].tagName')" + newest="$( + printf '%s\n' "$releases" "$GITHUB_REF_NAME" \ + | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 + )" + if [ "$newest" = "$version" ]; then latest=true; fi + fi + echo "marking $GITHUB_REF_NAME latest: $latest" + gh release edit "$GITHUB_REF_NAME" --draft=false --latest="$latest" --repo "$GITHUB_REPOSITORY" diff --git a/justfile b/justfile index 8dd6e29..65a7047 100644 --- a/justfile +++ b/justfile @@ -41,9 +41,12 @@ no-ort: package *args: #!/usr/bin/env bash set -euo pipefail - rm -rf target/package + # cargo package writes under the effective target directory, which + # CARGO_TARGET_DIR or build.target-dir can move away from ./target + target=$(cargo metadata --format-version 1 --no-deps | jq -r .target_directory) + rm -rf "$target/package" cargo package --locked {{args}} - crate=$(find target/package -maxdepth 1 -name 'scriptrs-*.crate' -print -quit) + crate=$(find "$target/package" -maxdepth 1 -name 'scriptrs-*.crate' -print -quit) test -n "$crate" # crates.io rejects uploads over 10 MiB unless it raises the crate's limit size=$(wc -c < "$crate") @@ -56,7 +59,7 @@ package *args: package=$(find "$work" -mindepth 1 -maxdepth 1 -type d -print -quit) # each consumer is its own workspace in a new directory, so keep its build files # in this target too rather than in a fresh build directory per run - export CARGO_TARGET_DIR="$PWD/target/package-consumers" + export CARGO_TARGET_DIR="$target/package-consumers" export CARGO_BUILD_BUILD_DIR="$CARGO_TARGET_DIR/build" consumer() {