sherpa-onnx JNI for speech, sharing Java decisions' ONNX Runtime on the macOS ARM64 and Linux release platforms. The upstream per-platform jar still bundles an older runtime; Vis extracts its JNI only and stages it beside ONNX Runtime Java 1.30.0. Unsupported platforms retain upstream's pair.
On a plain JVM the platform jar is downloaded on first speech use; native
images embed only the host JNI. Both loaders use one versioned directory.
A user-supplied sherpa_onnx.native.path remains authoritative.
The JitPack jar is length-checked and installed atomically; it is fetched
from the original publisher, not mirrored by Vis. Its JNI answers the
pinned version, as sherpa-test asserts.
;; JNI and not java.lang.foreign, because the choice is upstream's: the library
;; Vis ships, libsherpa-onnx-jni, exports 133 Java_* entry points and not one
;; SherpaOnnx* C symbol, so a Panama downcall has nothing to bind to. sherpa's C
;; API is a separate artifact — per-platform tarballs under no Maven coordinate —
;; whose 156 functions over 86 structs would leave us owning their layouts. Vis
;; does use FFM where it owns the boundary (internal/foundation/pty); here the
;; image registers the API jar's types for JNI instead
;; (reachability-metadata.json, pinned by sherpa-test).
sherpa-onnx JNI for speech, sharing Java decisions' ONNX Runtime on the macOS ARM64 and Linux release platforms. The upstream per-platform jar still bundles an older runtime; Vis extracts its JNI only and stages it beside ONNX Runtime Java 1.30.0. Unsupported platforms retain upstream's pair. On a plain JVM the platform jar is downloaded on first speech use; native images embed only the host JNI. Both loaders use one versioned directory. A user-supplied `sherpa_onnx.native.path` remains authoritative. The JitPack jar is length-checked and installed atomically; it is fetched from the original publisher, not mirrored by Vis. Its JNI answers the pinned `version`, as `sherpa-test` asserts. ;; JNI and not `java.lang.foreign`, because the choice is upstream's: the library ;; Vis ships, `libsherpa-onnx-jni`, exports 133 `Java_*` entry points and not one ;; `SherpaOnnx*` C symbol, so a Panama downcall has nothing to bind to. sherpa's C ;; API is a separate artifact — per-platform tarballs under no Maven coordinate — ;; whose 156 functions over 86 structs would leave us owning their layouts. Vis ;; does use FFM where it owns the boundary (`internal/foundation/pty`); here the ;; image registers the API jar's types for JNI instead ;; (`reachability-metadata.json`, pinned by `sherpa-test`).
(call-native f)Run f with the native runtime provisioned, reporting a linker failure -
here or inside sherpa's own loader - as native-failure rather than as a
stack trace. Every engine entry point goes through this, so no surface has to
know what a JNI is to tell a human what to do.
A linker failure met HERE is also handed to the host, because this is where it is normally met: sherpa loads its library from the static initializer of the first class a call touches, long after provisioning answered. Recording it is what stops every later call from fetching 13 MB to meet the same wall.
Run `f` with the native runtime provisioned, reporting a linker failure - here or inside sherpa's own loader - as [[native-failure]] rather than as a stack trace. Every engine entry point goes through this, so no surface has to know what a JNI is to tell a human what to do. A linker failure met HERE is also handed to the host, because this is where it is normally met: sherpa loads its library from the static initializer of the first class a call touches, long after provisioning answered. Recording it is what stops every later call from fetching 13 MB to meet the same wall.
(default-native-dir)(default-native-dir token)Versioned default path, computed at runtime rather than captured in the image.
Versioned default path, computed at runtime rather than captured in the image.
(embedded?)(embedded? token)True when this platform's Sherpa JNI is a classpath resource.
True when this platform's Sherpa JNI is a classpath resource.
(ensure-native!)Make sherpa's JNI loadable, ONCE, and return how: {:source :property |:embedded|:downloaded :platform <token> :dir <path?>}. Every entry point
that touches a com.k2fsa.sherpa.onnx class calls this first, because the
class's static initializer is what runs sherpa's loader — after that first
touch, a missing library is an UnsatisfiedLinkError no property can undo.
Whether an answer is worth keeping is the HOST's rule, not this pack's: a download that failed is retried on the next call, while a library this JVM has already refused to link is answered from memory instead of fetched again.
Make sherpa's JNI loadable, ONCE, and return how: `{:source :property
|:embedded|:downloaded :platform <token> :dir <path?>}`. Every entry point
that touches a `com.k2fsa.sherpa.onnx` class calls this first, because the
class's static initializer is what runs sherpa's loader — after that first
touch, a missing library is an `UnsatisfiedLinkError` no property can undo.
Whether an answer is worth keeping is the HOST's rule, not this pack's: a
download that failed is retried on the next call, while a library this JVM has
already refused to link is answered from memory instead of fetched again.(installed? dir)True when both of Sherpa's required native libraries exist.
True when both of Sherpa's required native libraries exist.
(jar-url token)Where the platform jar comes from, and the ONE place a Vis release does not
mirror. sherpa's VITS path phonemizes through espeak-ng, which is compiled
INTO libsherpa-onnx-jni — 10 espeak_* symbols and its data paths are in
the shipped library — so the jar is GPL-3 object code. It is fetched by the
user from the project that published it and is never re-hosted by Vis.
Where the platform jar comes from, and the ONE place a Vis release does not mirror. sherpa's VITS path phonemizes through espeak-ng, which is compiled INTO `libsherpa-onnx-jni` — 10 `espeak_*` symbols and its data paths are in the shipped library — so the jar is GPL-3 object code. It is fetched by the user from the project that published it and is never re-hosted by Vis.
(library-names)Sherpa's runtime and JNI filenames, in its native loading order.
Sherpa's runtime and JNI filenames, in its native loading order.
(native-failure t)Turn a linker failure into an ex-info a HUMAN can act on.
A class whose static initializer already failed can NEVER load again in the
same process - the JVM caches that verdict - so an engine that met a missing
library once keeps answering NoClassDefFoundError however much is downloaded
afterwards. That is exactly the reported "voice only works after restarting
Vis", so in that state the message SAYS to restart instead of repeating a
linker error nobody can act on.
Turn a linker failure into an ex-info a HUMAN can act on. A class whose static initializer already failed can NEVER load again in the same process - the JVM caches that verdict - so an engine that met a missing library once keeps answering `NoClassDefFoundError` however much is downloaded afterwards. That is exactly the reported "voice only works after restarting Vis", so in that state the message SAYS to restart instead of repeating a linker error nobody can act on.
Sherpa's override: a directory containing its JNI and ONNX Runtime.
Sherpa's override: a directory containing its JNI and ONNX Runtime.
(platform-token)(platform-token os-name os-arch)Sherpa's native/<token> directory name; both Java loaders use this token.
Sherpa's `native/<token>` directory name; both Java loaders use this token.
Platforms with an upstream Sherpa native jar. Other OS/CPU pairs require a user-provided native build.
Platforms with an upstream Sherpa native jar. Other OS/CPU pairs require a user-provided native build.
The Sherpa JNI and Java API release; the shared runtime has its own pin.
The Sherpa JNI and Java API release; the shared runtime has its own pin.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |