Publish experimental ARK 0.6B Q8 GGUF with provenance and validation

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+ark-asr-0.6b-Q8_0.gguf filter=lfs diff=lfs merge=lfs -text

CONVERTER-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The transcribe.cpp authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,107 @@
+---
+license: apache-2.0
+base_model: Edge0/ARK-ASR-0.6B
+pipeline_tag: automatic-speech-recognition
+language:
+- zh
+- en
+- de
+- ja
+- fr
+- ko
+- es
+- pl
+- it
+- ro
+- hu
+- cs
+- nl
+- fi
+- hr
+- sk
+- sl
+- et
+- lt
+tags:
+- gguf
+- arkasr
+- transcribe.cpp
+---
+
+# ARK-ASR-0.6B GGUF candidate
+
+Community Q8 conversion of [Edge0/ARK-ASR-0.6B](https://huggingface.co/Edge0/ARK-ASR-0.6B),
+prepared for a draft Hex integration. No retraining. Not affiliated with the
+original authors, and not a canonical handy-computer artifact.
+
+**Requires an ARK-enabled runtime.** Stock llama.cpp, whisper.cpp and released
+transcribe-cpp 0.2.4 cannot load it. Use the candidate runtime at
+[maxffarrell/transcribe.cpp](https://github.com/maxffarrell/transcribe.cpp/tree/19f301609c06126e5071d1de5acdd95c714eec05),
+revision `19f301609c06126e5071d1de5acdd95c714eec05`.
+[Upstream draft PR](https://github.com/handy-computer/transcribe.cpp/pull/191).
+
+## File
+
+`ark-asr-0.6b-Q8_0.gguf`: 1,372,881,664 bytes.
+SHA-256: `ceca6bacd9cab3b52892de6703562aeeb62dc8a4b14aab0b020706637dd127dc`.
+
+The 0.6B name describes the decoder; the full model also contains the audio
+encoder and adapter. Q8 linear weights, F16 tied embedding/output matrix and
+convolutions, F32 norms/biases/frontend tensors.
+
+## Run
+
+```sh
+git clone https://github.com/maxffarrell/transcribe.cpp
+cd transcribe.cpp
+git checkout 19f301609c06126e5071d1de5acdd95c714eec05
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTRANSCRIBE_BUILD_EXAMPLES=ON
+cmake --build build --target transcribe-cli -j 8
+hf download maxffarrell/ARK-ASR-0.6B-GGUF ark-asr-0.6b-Q8_0.gguf --local-dir models/ark
+build/bin/transcribe-cli --backend metal -m models/ark/ark-asr-0.6b-Q8_0.gguf audio.wav
+```
+
+Use `--backend cpu` for CPU inference. Input frontend: mono 16 kHz.
+Long recordings use overlapping windows of at most 30 seconds. Language is
+inferred from audio; forced-language steering, translation, streaming and
+timestamps are not supported by this candidate.
+
+## Validation and limitations
+
+Six public short samples from transcribe.cpp (JFK, Mandarin, Japanese, Korean,
+noise and silence) produced exactly matching text in the original PyTorch
+checkpoint, F16 GGUF and this Q8 GGUF. The Q8 JFK transcript also matched on
+CPU and Metal. A 197-second public English speech clip completed through the
+runtime's overlapping-window path on Metal. The existing 45 runtime CTests
+passed. See `validation.json` for the compared text.
+
+Reference agreement is not a ground-truth WER measurement. The original model
+and both GGUF precisions emitted Japanese text for the Korean sample and
+`嗯。` for noise and silence. Automatic language detection and hallucination
+on nonspeech remain material limitations. The publisher's 19-language list
+is coverage metadata, not validation of all languages. Long-audio completion
+does not establish parity against an unchunked reference. Full tensor parity,
+WER evaluation and upstream port acceptance remain incomplete. Treat this as
+an experimental model, not an accuracy or speed recommendation.
+
+## Reproduce
+
+Source: `Edge0/ARK-ASR-0.6B@45776b56d58cdfb2e2eb632f7e110f38684633e0`.
+Original `model.safetensors` SHA-256:
+`57a86ce1c2f2c2d6ebb7ad9642c9e951a5109625122b48c9180126a28787673d`.
+
+```sh
+uv run convert-arkasr-to-gguf.py --input Edge0/ARK-ASR-0.6B \
+  --revision 45776b56d58cdfb2e2eb632f7e110f38684633e0 \
+  --variant ark-asr-0.6b --outtype q8_0 --output ark-asr-0.6b-Q8_0.gguf
+```
+
+The included converter reuses harshav's work from
+[ARK-ASR-3B-GGUF](https://huggingface.co/harshav/ARK-ASR-3B-GGUF), with variant,
+revision and capability metadata adapted for 0.6B. Its source archive is pinned
+in `conversion.json`. Converter/runtime license: MIT (`CONVERTER-LICENSE`);
+weights: Apache-2.0 (`LICENSE`). Original architecture, training and evaluation:
+[AutoArk/open-audio-opd](https://github.com/AutoArk/open-audio-opd).
+
+This community conversion and its draft integration were prepared with Codex
+at the contributor's request.

ark-asr-0.6b-Q8_0.gguf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ceca6bacd9cab3b52892de6703562aeeb62dc8a4b14aab0b020706637dd127dc
+size 1372881664

conversion.json

@@ -0,0 +1,20 @@
+{
+  "source_repository": "Edge0/ARK-ASR-0.6B",
+  "source_revision": "45776b56d58cdfb2e2eb632f7e110f38684633e0",
+  "source_sha256": "57a86ce1c2f2c2d6ebb7ad9642c9e951a5109625122b48c9180126a28787673d",
+  "output_file": "ark-asr-0.6b-Q8_0.gguf",
+  "output_bytes": 1372881664,
+  "output_sha256": "ceca6bacd9cab3b52892de6703562aeeb62dc8a4b14aab0b020706637dd127dc",
+  "converter_revision": "19f301609c06126e5071d1de5acdd95c714eec05",
+  "reused_runtime_source": "https://huggingface.co/harshav/ARK-ASR-3B-GGUF/resolve/main/transcribe.cpp-arkasr-b838a2b.tar.gz",
+  "reused_source_sha256": "776c2a7a690dc21dc629aa79d03003a0a9f9a463f1e0a4f3a4cefc6ee59dbe97",
+  "versions": {
+    "torch": "2.14.1",
+    "numpy": "2.5.3",
+    "gguf": "0.19.0",
+    "safetensors": "0.8.0",
+    "transformers": "4.57.6",
+    "huggingface-hub": "0.36.2"
+  },
+  "command": "uv run convert-arkasr-to-gguf.py --input Edge0/ARK-ASR-0.6B --revision 45776b56d58cdfb2e2eb632f7e110f38684633e0 --variant ark-asr-0.6b --outtype q8_0 --output ark-asr-0.6b-Q8_0.gguf"
+}

convert-arkasr-to-gguf.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.12,<3.15"
+# dependencies = [
+#   "gguf",
+#   "huggingface-hub",
+#   "numpy",
+#   "safetensors",
+#   "torch",
+#   "transformers",
+# ]
+# ///
+"""Convert ARK-ASR 0.6B or 3B to GGUF format for transcribe.cpp.
+
+Architecture (see PLAN.md §ARK):
+  * Audio encoder: Whisper-large-v3 (128 mel, d_model 1280, 32 layers, 20 heads)
+    with *partial interleaved RoPE* (rot_dim 32 of head_dim 64, theta 10000,
+    Q+K only); k_proj has no bias; the encoder's own final LayerNorm is dropped
+    (nn.Identity).
+  * Adapter: LayerNorm(1280) -> merge 4 consecutive frames (->5120) ->
+    Linear 5120->4096 -> GELU -> Linear 4096->2048.
+  * Decoder: stock Qwen2.5-3B (2048 hid, 36 L, GQA 16/2, SwiGLU, RMSNorm,
+    rope_theta 1e6, vocab 151936, tied embeddings).
+
+Audio placeholder token <|audio|> (151663) embeddings are replaced by the first
+N = ((mel_frames+1)//2)//4 adapter frames.
+
+Streams tensors one-at-a-time via safe_open (BF16->F16). ~9 GB peak RAM.
+
+Usage:
+    uv run --python 3.12 scripts/convert-arkasr-to-gguf.py --input AutoArk-AI/ARK-ASR-3B \
+        --output arkasr-3b-f16.gguf --outtype f16
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import torch
+
+try:
+    from gguf import GGUFWriter, GGMLQuantizationType
+except ImportError:
+    print("Error: gguf package not found. Install with: pip install gguf")
+    sys.exit(1)
+
+try:
+    from safetensors import safe_open
+except ImportError:
+    print("Error: safetensors package not found. Install with: pip install safetensors")
+    sys.exit(1)
+
+try:
+    from huggingface_hub import snapshot_download
+except ImportError:
+    snapshot_download = None
+
+
+def load_model_dir(model_id: str, revision: str | None = None) -> Path:
+    p = Path(model_id)
+    if p.is_dir():
+        return p
+    if snapshot_download is None:
+        print("Error: huggingface_hub not installed and --input is not a local dir")
+        sys.exit(1)
+    print(f"Downloading model from HuggingFace: {model_id}")
+    return Path(snapshot_download(
+        model_id, revision=revision,
+        allow_patterns=["*.safetensors", "*.json", "merges.txt", "*.jinja"],
+    ))
+
+
+def map_tensor_name(name: str):
+    """Map an HF tensor name to a GGUF name, or None to skip it."""
+    # --- decoder (Qwen2.5-3B) ---
+    if name == "model.embed_tokens.weight":
+        return "dec.embed.weight"
+    if name == "model.norm.weight":
+        return "dec.norm.weight"
+    if name == "lm_head.weight":
+        return None  # tied to dec.embed.weight; reused at runtime
+    if name.startswith("model.layers."):
+        rest = name[len("model.layers."):]
+        idx, _, sub = rest.partition(".")
+        m = {
+            "self_attn.q_proj.weight": "attn.q.weight",
+            "self_attn.q_proj.bias": "attn.q.bias",
+            "self_attn.k_proj.weight": "attn.k.weight",
+            "self_attn.k_proj.bias": "attn.k.bias",
+            "self_attn.v_proj.weight": "attn.v.weight",
+            "self_attn.v_proj.bias": "attn.v.bias",
+            "self_attn.o_proj.weight": "attn.o.weight",
+            "input_layernorm.weight": "attn_norm.weight",
+            "post_attention_layernorm.weight": "ffn_norm.weight",
+            "mlp.gate_proj.weight": "ffn.gate.weight",
+            "mlp.up_proj.weight": "ffn.up.weight",
+            "mlp.down_proj.weight": "ffn.down.weight",
+        }.get(sub)
+        return f"dec.blk.{idx}.{m}" if m else None
+
+    # --- adapter ---
+    if name == "audio_encoder.layer_norm.weight":
+        return "adapter.ln.weight"
+    if name == "audio_encoder.layer_norm.bias":
+        return "adapter.ln.bias"
+    if name == "audio_encoder.adapting.0.weight":
+        return "adapter.fc1.weight"
+    if name == "audio_encoder.adapting.0.bias":
+        return "adapter.fc1.bias"
+    if name == "audio_encoder.adapting.2.weight":
+        return "adapter.fc2.weight"
+    if name == "audio_encoder.adapting.2.bias":
+        return "adapter.fc2.bias"
+
+    # --- whisper encoder ---
+    if name.startswith("audio_encoder.whisper."):
+        rest = name[len("audio_encoder.whisper."):]
+        if rest == "conv1.weight":
+            return "enc.conv1.weight"
+        if rest == "conv1.bias":
+            return "enc.conv1.bias"
+        if rest == "conv2.weight":
+            return "enc.conv2.weight"
+        if rest == "conv2.bias":
+            return "enc.conv2.bias"
+        if rest == "embed_positions.weight":
+            return None  # unused (use_rope=True)
+        if rest in ("layer_norm.weight", "layer_norm.bias"):
+            return None  # encoder final LN replaced by nn.Identity
+        if rest.startswith("layers."):
+            r2 = rest[len("layers."):]
+            idx, _, sub = r2.partition(".")
+            m = {
+                "self_attn.q_proj.weight": "attn.q.weight",
+                "self_attn.q_proj.bias": "attn.q.bias",
+                "self_attn.k_proj.weight": "attn.k.weight",  # no bias
+                "self_attn.v_proj.weight": "attn.v.weight",
+                "self_attn.v_proj.bias": "attn.v.bias",
+                "self_attn.out_proj.weight": "attn.o.weight",
+                "self_attn.out_proj.bias": "attn.o.bias",
+                "self_attn_layer_norm.weight": "attn_ln.weight",
+                "self_attn_layer_norm.bias": "attn_ln.bias",
+                "fc1.weight": "fc1.weight",
+                "fc1.bias": "fc1.bias",
+                "fc2.weight": "fc2.weight",
+                "fc2.bias": "fc2.bias",
+                "final_layer_norm.weight": "ffn_ln.weight",
+                "final_layer_norm.bias": "ffn_ln.bias",
+            }.get(sub)
+            return f"enc.blk.{idx}.{m}" if m else None
+        return None
+    return None
+
+
+def build_mel_and_window(n_fft: int, n_mels: int, sr: int):
+    """Whisper feature-extractor mel filterbank (n_freqs, n_mels) + hann window.
+
+    Mirrors transformers.WhisperFeatureExtractor: slaney mel scale + slaney
+    norm, 0..sr/2 Hz, and torch.hann_window(periodic=True)."""
+    from transformers.audio_utils import mel_filter_bank
+    n_freqs = 1 + n_fft // 2
+    fb = mel_filter_bank(
+        num_frequency_bins=n_freqs,
+        num_mel_filters=n_mels,
+        min_frequency=0.0,
+        max_frequency=float(sr) / 2.0,
+        sampling_rate=sr,
+        norm="slaney",
+        mel_scale="slaney",
+    )  # (n_freqs, n_mels) float32
+    fb = np.ascontiguousarray(fb, dtype=np.float32)
+    # periodic hann window of length n_fft
+    win = np.hanning(n_fft + 1)[:-1].astype(np.float32)
+    return fb, win
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert ARK-ASR-3B to GGUF")
+    ap.add_argument("--input", required=True, help="HF model ID or local dir")
+    ap.add_argument("--output", required=True, help="Output GGUF path")
+    ap.add_argument("--outtype", default="f16", choices=["f16", "f32", "q8_0"],
+                    help="dtype for 2D weights (default f16). q8_0 quantizes 2D "
+                         "decoder/encoder/adapter weights; keeps the tied embedding, "
+                         "conv kernels (F16) and norms/filterbank (F32).")
+    ap.add_argument("--variant", required=True, choices=["ark-asr-0.6b", "ark-asr-3b"])
+    ap.add_argument("--revision", help="Pinned Hugging Face source revision")
+    args = ap.parse_args()
+
+    mdir = load_model_dir(args.input, args.revision)
+    with open(mdir / "config.json", encoding="utf-8") as f:
+        cfg = json.load(f)
+    wc = cfg["whisper_config"]
+    expected_hidden = {"ark-asr-0.6b": 896, "ark-asr-3b": 2048}[args.variant]
+    if cfg["model_type"] != "arkasr" or cfg["hidden_size"] != expected_hidden:
+        raise ValueError("Checkpoint does not match the selected ARK variant")
+    if not cfg.get("tie_word_embeddings") or not cfg.get("use_rope"):
+        raise ValueError("ARK runtime requires tied embeddings and RoPE")
+
+    w = GGUFWriter(args.output, "arkasr")
+    w.add_name(args.variant.upper())
+    w.add_string("stt.variant", args.variant)
+    w.add_bool("stt.capability.lang_detect", True)
+    w.add_array("general.languages", ["zh", "en", "de", "ja", "fr", "ko", "es", "pl", "it", "ro", "hu", "cs", "nl", "fi", "hr", "sk", "sl", "et", "lt"] if args.variant == "ark-asr-0.6b" else ["zh", "en", "de", "ja", "fr", "ko", "es"])
+    w.add_description("ARK-ASR (Whisper-RoPE encoder + Qwen2 decoder)")
+
+    # ---- decoder (Qwen2.5-3B) hparams ----
+    hid = int(cfg["hidden_size"])
+    n_heads = int(cfg["num_attention_heads"])
+    w.add_uint32("arkasr.llm.hidden_size", hid)
+    w.add_uint32("arkasr.llm.num_layers", int(cfg["num_hidden_layers"]))
+    w.add_uint32("arkasr.llm.num_heads", n_heads)
+    w.add_uint32("arkasr.llm.num_kv_heads", int(cfg["num_key_value_heads"]))
+    w.add_uint32("arkasr.llm.head_dim", hid // n_heads)
+    w.add_uint32("arkasr.llm.intermediate_size", int(cfg["intermediate_size"]))
+    w.add_uint32("arkasr.llm.vocab_size", int(cfg["vocab_size"]))
+    w.add_uint32("arkasr.llm.max_position_embeddings", int(cfg.get("max_position_embeddings", 32768)))
+    w.add_float32("arkasr.llm.rope_theta", float(cfg.get("rope_theta", 1000000.0)))
+    w.add_float32("arkasr.llm.rms_norm_eps", float(cfg.get("rms_norm_eps", 1e-6)))
+
+    # ---- whisper encoder hparams ----
+    d_model = int(wc["d_model"])
+    e_heads = int(wc["encoder_attention_heads"])
+    e_head_dim = d_model // e_heads
+    w.add_uint32("arkasr.whisper.d_model", d_model)
+    w.add_uint32("arkasr.whisper.num_layers", int(wc["encoder_layers"]))
+    w.add_uint32("arkasr.whisper.num_heads", e_heads)
+    w.add_uint32("arkasr.whisper.head_dim", e_head_dim)
+    w.add_uint32("arkasr.whisper.ffn_dim", int(wc["encoder_ffn_dim"]))
+    w.add_uint32("arkasr.whisper.num_mel_bins", int(wc["num_mel_bins"]))
+    w.add_uint32("arkasr.whisper.max_source_positions", int(wc["max_source_positions"]))
+    # RotaryEmbedding(dim = head_dim // 2), base 10000 (rope_ratio 1)
+    w.add_uint32("arkasr.whisper.rot_dim", e_head_dim // 2)
+    w.add_float32("arkasr.whisper.rope_theta", 10000.0)
+    w.add_float32("arkasr.whisper.ln_eps", 1e-5)
+
+    # ---- adapter / audio / tokenizer hparams ----
+    w.add_uint32("arkasr.adapter.merge_factor", int(cfg.get("merge_factor", 4)))
+    w.add_uint32("arkasr.audio_token_id", int(cfg["audio_token_id"]))
+    w.add_uint32("arkasr.bos_token_id", int(cfg.get("bos_token_id", 151643)))
+    w.add_uint32("arkasr.eos_token_id", int(cfg.get("eos_token_id", 151645)))
+    w.add_uint32("arkasr.pad_token_id", int(cfg.get("pad_token_id", 151643)))
+    w.add_uint32("arkasr.n_fft", 400)
+    w.add_uint32("arkasr.hop_length", 160)
+    w.add_uint32("arkasr.sample_rate", 16000)
+
+    # ---- mel filterbank + window ----
+    fb, win = build_mel_and_window(400, int(wc["num_mel_bins"]), 16000)
+    w.add_tensor("enc.mel_filters", fb, raw_dtype=GGMLQuantizationType.F32)
+    w.add_tensor("enc.mel_window", win, raw_dtype=GGMLQuantizationType.F32)
+
+    # ---- tokenizer: GPT-2 byte-level BPE (vocab + merges + specials) ----
+    vocab_size = int(cfg["vocab_size"])
+    tokens = [f"[PAD{i}]" for i in range(vocab_size)]
+    vj = mdir / "vocab.json"
+    if vj.exists():
+        with open(vj, encoding="utf-8") as f:
+            vmap = json.load(f)
+        for tok, idx in vmap.items():
+            if 0 <= idx < vocab_size:
+                tokens[idx] = tok
+    aj = mdir / "added_tokens.json"
+    if aj.exists():
+        with open(aj, encoding="utf-8") as f:
+            for tok, idx in json.load(f).items():
+                if 0 <= idx < vocab_size:
+                    tokens[idx] = tok
+    w.add_tokenizer_model("gpt2")
+    w.add_token_list(tokens)
+    mt = mdir / "merges.txt"
+    if mt.exists():
+        merges = []
+        with open(mt, encoding="utf-8") as f:
+            for line in f:
+                line = line.rstrip("\n")
+                if line and not line.startswith("#"):
+                    merges.append(line)
+        if merges:
+            w.add_token_merges(merges)
+    else:
+        print("WARNING: merges.txt missing — decode-only is fine, encode falls back to per-byte")
+
+    # ---- stream tensors ----
+    index_path = mdir / "model.safetensors.index.json"
+    if index_path.exists():
+        with open(index_path, encoding="utf-8") as f:
+            weight_map = json.load(f)["weight_map"]
+    else:
+        # single-file checkpoint
+        only = next(mdir.glob("*.safetensors"))
+        weight_map = {}
+        with safe_open(str(only), framework="pt") as h:
+            for k in h.keys():
+                weight_map[k] = only.name
+
+    handles = {}
+    def get_handle(fname):
+        if fname not in handles:
+            handles[fname] = safe_open(str(mdir / fname), framework="pt")
+        return handles[fname]
+
+    # q8_0: keep these at F16/F32 (sampling-critical / conv / filterbank).
+    def keep_unquantized(name):
+        return (name == "dec.embed.weight" or name.endswith("conv1.weight") or name.endswith("conv2.weight"))
+
+    try:
+        from gguf import quants as _gguf_quants
+    except ImportError:
+        _gguf_quants = None
+
+    n_written = 0
+    n_quant = 0
+    for hf_name in sorted(weight_map.keys()):
+        gguf_name = map_tensor_name(hf_name)
+        if gguf_name is None:
+            continue
+        t = get_handle(weight_map[hf_name]).get_tensor(hf_name)
+        if t.ndim <= 1:
+            data = np.ascontiguousarray(t.to(torch.float32).numpy())
+            w.add_tensor(gguf_name, data, raw_dtype=GGMLQuantizationType.F32)
+        elif args.outtype == "q8_0" and t.ndim == 2 and not keep_unquantized(gguf_name) \
+                and (t.shape[-1] % 32 == 0) and _gguf_quants is not None:
+            arr = np.ascontiguousarray(t.to(torch.float32).numpy())
+            qd = _gguf_quants.quantize(arr, GGMLQuantizationType.Q8_0)
+            w.add_tensor(gguf_name, qd, raw_dtype=GGMLQuantizationType.Q8_0)
+            n_quant += 1
+        else:
+            dt = torch.float32 if args.outtype == "f32" else torch.float16
+            qt = GGMLQuantizationType.F32 if args.outtype == "f32" else GGMLQuantizationType.F16
+            data = np.ascontiguousarray(t.to(dt).numpy())
+            w.add_tensor(gguf_name, data, raw_dtype=qt)
+        n_written += 1
+        if n_written % 50 == 0:
+            print(f"  ... {n_written} tensors ({n_quant} q8_0)")
+
+    print(f"Writing GGUF ({n_written} tensors) -> {args.output}")
+    w.write_header_to_file()
+    w.write_kv_data_to_file()
+    w.write_tensors_to_file()
+    w.close()
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

validation.json

@@ -0,0 +1,56 @@
+{
+  "runtime_revision": "19f301609c06126e5071d1de5acdd95c714eec05",
+  "samples_source": "handy-computer/transcribe.cpp@48559bbd9a44320f1b581606f712ce1dd0e2309f",
+  "short_cases": [
+    {
+      "sample": "jfk.wav",
+      "pytorch": "And so, my fellow Americans, ask not what your country can do for you; ask what you can do for your country.",
+      "f16": "And so, my fellow Americans, ask not what your country can do for you; ask what you can do for your country.",
+      "q8_0": "And so, my fellow Americans, ask not what your country can do for you; ask what you can do for your country.",
+      "exact": true
+    },
+    {
+      "sample": "zh-short.wav",
+      "pytorch": "\u65e5\u672c\u539f\u5b50\u80fd\u673a\u6784\u8868\u793a\uff0c\u6838\u7535\u7ad9\u68c0\u6d4b\u51fa\u4e86\u653e\u5c04\u6027\u7269\u8d28\u201c\u7130\u201d\u6838\u70b9\u3002",
+      "f16": "\u65e5\u672c\u539f\u5b50\u80fd\u673a\u6784\u8868\u793a\uff0c\u6838\u7535\u7ad9\u68c0\u6d4b\u51fa\u4e86\u653e\u5c04\u6027\u7269\u8d28\u201c\u7130\u201d\u6838\u70b9\u3002",
+      "q8_0": "\u65e5\u672c\u539f\u5b50\u80fd\u673a\u6784\u8868\u793a\uff0c\u6838\u7535\u7ad9\u68c0\u6d4b\u51fa\u4e86\u653e\u5c04\u6027\u7269\u8d28\u201c\u7130\u201d\u6838\u70b9\u3002",
+      "exact": true
+    },
+    {
+      "sample": "ja-short.wav",
+      "pytorch": "\u3057\u304b\u3057\u3001\u901a\u4fe1\u7d4c\u8def\u304c\u9045\u3044\u305f\u3081\u3001\u897f\u6d0b\u306e\u30b9\u30bf\u30a4\u30eb\u306f25\u5e74\u304b\u308930\u5e74\u9045\u308c\u3066\u3044\u308b\u53ef\u80fd\u6027\u304c\u3042\u308a\u307e\u3059\u3002",
+      "f16": "\u3057\u304b\u3057\u3001\u901a\u4fe1\u7d4c\u8def\u304c\u9045\u3044\u305f\u3081\u3001\u897f\u6d0b\u306e\u30b9\u30bf\u30a4\u30eb\u306f25\u5e74\u304b\u308930\u5e74\u9045\u308c\u3066\u3044\u308b\u53ef\u80fd\u6027\u304c\u3042\u308a\u307e\u3059\u3002",
+      "q8_0": "\u3057\u304b\u3057\u3001\u901a\u4fe1\u7d4c\u8def\u304c\u9045\u3044\u305f\u3081\u3001\u897f\u6d0b\u306e\u30b9\u30bf\u30a4\u30eb\u306f25\u5e74\u304b\u308930\u5e74\u9045\u308c\u3066\u3044\u308b\u53ef\u80fd\u6027\u304c\u3042\u308a\u307e\u3059\u3002",
+      "exact": true
+    },
+    {
+      "sample": "ko-short.wav",
+      "pytorch": "\u7121\u7406\u306f\u3001\u4e00\u5339\u304b\u3089\u4e09\u5339\u306e\u540c\u65cf\u6210\u4eba\u30b9\u30b3\u30c3\u30af\u3068\u3001\u3080\u3084\u4e09\u5341\u5339\u306b\u3044\u308b\u306e\u30a2\u30f3\u30b3\u30c3\u30af\u3068\u4e09\u5339\u3067\u69cb\u6210\u3055\u308c\u307e\u3059\u3002",
+      "f16": "\u7121\u7406\u306f\u3001\u4e00\u5339\u304b\u3089\u4e09\u5339\u306e\u540c\u65cf\u6210\u4eba\u30b9\u30b3\u30c3\u30af\u3068\u3001\u3080\u3084\u4e09\u5341\u5339\u306b\u3044\u308b\u306e\u30a2\u30f3\u30b3\u30c3\u30af\u3068\u4e09\u5339\u3067\u69cb\u6210\u3055\u308c\u307e\u3059\u3002",
+      "q8_0": "\u7121\u7406\u306f\u3001\u4e00\u5339\u304b\u3089\u4e09\u5339\u306e\u540c\u65cf\u6210\u4eba\u30b9\u30b3\u30c3\u30af\u3068\u3001\u3080\u3084\u4e09\u5341\u5339\u306b\u3044\u308b\u306e\u30a2\u30f3\u30b3\u30c3\u30af\u3068\u4e09\u5339\u3067\u69cb\u6210\u3055\u308c\u307e\u3059\u3002",
+      "exact": true
+    },
+    {
+      "sample": "noise.wav",
+      "pytorch": "\u55ef\u3002",
+      "f16": "\u55ef\u3002",
+      "q8_0": "\u55ef\u3002",
+      "exact": true
+    },
+    {
+      "sample": "jobs-silence.wav",
+      "pytorch": "\u55ef\u3002",
+      "f16": "\u55ef\u3002",
+      "q8_0": "\u55ef\u3002",
+      "exact": true
+    }
+  ],
+  "cpu_metal_jfk_exact": true,
+  "long_audio": {
+    "sample": "love-loss.wav",
+    "duration_seconds": 197.15,
+    "completion": "ok",
+    "reference_parity_checked": false
+  },
+  "is_ground_truth_wer": false
+}