[BBC-Esq]

Note

Description of this pull request

This PR lets the WhisperS2T presets run offline, the same way #4760 did for native Whisper and #4825 did for the native Distil-Whisper presets:

docling-tools models download whisper_small_en_s2t --output-dir /models
docling --asr-model whisper_small_en_s2t --artifacts-path /models audio.wav

Prefetch. docling-tools models download now accepts the 14 WhisperS2T presets under their --asr-model names. Each one downloads its CTranslate2 model in float16 (for CUDA) and float32 (for CPU), plus the word aligner that word timestamps use if the preset needs one. The files go into the output directory in the Hugging Face cache layout, the same layout that #4825 uses for the Distil checkpoints. Plain --all and --all --asr still exclude WhisperS2T models, because 14 presets at two precisions add about 40 GB.

Run. When artifacts_path is set, _WhisperS2TModel passes cache_dir=artifacts_path and local_files_only=True to whisper_s2t.load_model(), so the library loads the model and its word aligner from that folder and never downloads. If files are missing, Docling raises a FileNotFoundError, for example:

artifacts_path (/models) does not contain the float32 WhisperS2T files required by ASR model 'large-v3-turbo'. Prefetch them with: docling-tools models download whisper_large_v3_turbo_s2t --output-dir "/models"

Library. This uses the API that whisper-s2t-reborn 1.8.0 added for this purpose: download_model() with force_download, default_word_aligner(), and cache_dir and local_files_only in the loader, which reach both the model and its word aligner. The floor therefore rises to >=1.8.0,<2.0.0. The uv.lock change is only that version bump.

Precision. whisper-s2t-reborn publishes float32, float16 and bfloat16 models and runs every other precision as float32, and CTranslate2 needs float32 on CPU. A small helper applies both rules, so the prefetch, the run and the error message all name the files that the library actually loads. For this reason, test_whisper_s2t_cpu_preserves_cpu_compatible_compute_types became test_whisper_s2t_cpu_runs_other_compute_types_as_float32: int8 and int8_float32 already ran as float32.

I tested it end to end. I prefetched whisper_base_en_s2t into an empty folder (645 MB: base.en and its tiny.en aligner, each in float16 and float32). Then, with HF_HUB_OFFLINE=1, I ran it from the CLI on CPU and on CUDA, and from Python with word timestamps on both devices. The Python runs loaded the tiny.en aligner from the folder at the matching precision. An empty folder fails at once with the message above and stays empty.

Important

Related pull requests: step 4 of 4

These four pull requests add offline support (--artifacts-path and docling-tools models download) for the ASR presets I contributed in #2938 and #3741, the same way that Peter Staar did in #4760 for native Whisper. A checked box means that step is merged.

• Cleanup (refactor(asr): remove redundant n_mels override for WhisperS2T #4785): remove the redundant n_mels override in the WhisperS2T backend.
• PR A (feat(asr): prefetch the native Distil-Whisper presets with docling-tools #4825): add the native Distil-Whisper presets to docling-tools models download.
• whisper-s2t-reborn 1.8.0 (release): let the library load its models, including the word aligner, from a local folder.
• PR B: run the WhisperS2T presets offline from --artifacts-path, with prefetch through docling-tools models download. ⬅️ this PR

Related work for another backend: #4771 aims at the same goal for a new Transformers ASR backend (with MLX presets): its presets run Transformers-format checkpoints offline from --artifacts-path (#4684). This PR does not change the same lines. Both PRs change uv.lock, so if #4771 merges first, I will merge main into this branch and re-run uv lock.

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

[github-actions]

✅ DCO Check Passed

Thanks @BBC-Esq, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit 290a217241. The analysis read the diff only. It did not run code from this pull request.

The PR lets docling-tools models download fetch the 14 WhisperS2T presets (float16 and float32 models plus the word aligner). It makes _WhisperS2TModel load them offline from artifacts_path with local_files_only=True. If files are missing, it raises a FileNotFoundError that tells the user which prefetch command to run.

CI safety: needs maintainer care before you approve CI.

• pyproject.toml: changes build, dependency, or tool configuration
• uv.lock: changes locked dependencies

2 related pull request(s) in the same code

PR	State	Signal	Assessment
#4825	merged	referenced as #4825	related: The merged PR adds the same prefetch and offline flow for the native Distil-Whisper presets. This PR adds it for the WhisperS2T presets. It reuses the same CLI and downloader structure but changes different models.
#4760	merged	referenced as #4760	related: The merged PR adds prefetch and offline run for native Whisper. This PR does the same for WhisperS2T, in the same CLI and downloader code, and it removes the doc note that WhisperS2T is not prefetched.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the full diff at 539b3181c5. It read the code and did not run it.

The offline prefetch and load path looks consistent. One risk is that the PR changes how torch_dtype is mapped to compute_type for all WhisperS2T users, including users who do not use --artifacts-path. The reviewer must decide if dropping int8 and int8_float32 support is intended.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[codecov]

Codecov Report

❌ Patch coverage is 89.65517% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/utils/model_downloader.py	78.26%	3 Missing and 2 partials ⚠️
docling/pipeline/asr_transcriber.py	91.66%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[geoHeil]

Reviewed 539b3181c5d520cb460da8ee3fefb91f58a02793. No code blocker found. The author reply about int8 is correct: WhisperS2T 1.7.1 already maps it to float32. The 1.8.0 API forwards the cache directory and offline flag to the model and its word aligner.

Local validation: 56 tests pass, with two dependency skips. The real hub boundary checks also pass. Linux CI now passes both new offline tests with WhisperS2T 1.8.0. Current CI is green. Codecov patch coverage is 89.65517%. Full CPU/CUDA transcription was not repeated locally.

Local make check stops on file-length violations that already exist on base. The other read-only checks pass. I made no source or reference-data changes.

[github-actions]

AI first review (advisory): no blocker found

This review covers the changes since 539b3181c5 at 290a217241. It read the code and did not run it.

The incremental diff only brings in changes from the base branch. It does not touch any WhisperS2T file in this PR, so there is nothing new to report. The earlier compute-type question is answered, but its main claim is not confirmed here. whisper-s2t-reborn is not installed in the workspace, so the maintainer should read _normalize_compute_type in the 1.7.1 release to confirm it.

Earlier findings

• answered (question): Compute types other than float32/float16/bfloat16 are now silently changed to float32, on CPU and CUDA

_{A maintainer makes the merge decision. This review never approves the pull request.}

[geoHeil]

Reviewed head 290a2172415bbebd274d3c160d158dfb61644110.

No blocker found. The CLI model names map to all 14 WhisperS2T presets, --all still excludes them, and named prefetch downloads the model plus the required word aligner in both CPU (float32) and CUDA (float16) variants. With whisper-s2t-reborn 1.8.0, an empty --artifacts-path raises LocalEntryNotFoundError, which this change converts to the documented actionable FileNotFoundError; the local-only flags reach both model and aligner loads.

Validation: hosted CI is green, including Python 3.10–3.14 core tests, ASR tests, package tests, lint, type, Tach, docs, and Codecov. I also checked the 1.8.0 loader/download contracts directly and reproduced the empty-cache exception. Full CPU/CUDA transcription was not repeated locally.

[PeterStaar-IBM]

lgtm!