@nicfox77/parakeet-stt 0.2.0

package/README.md

@@ -0,0 +1,101 @@
+# Parakeet STT for OpenClaw
+
+Fast CPU-based speech-to-text using NVIDIA's Parakeet TDT INT8 models.
+
+## Features
+
+- **4x faster than real-time** (0.25x RTF)
+- **CPU-only** - no GPU required
+- **Two model versions:**
+  - **V2** - English optimized (higher accuracy for English)
+  - **V3** - Multilingual (25 European languages, auto-detect)
+- **Lazy loading** - model loads on first transcription, unloads after inactivity
+
+## Installation
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install @nicfox77/parakeet-stt
+```
+
+### 2. Install a model
+
+```bash
+# English optimized (default)
+~/.openclaw/extensions/parakeet-stt/scripts/install.sh v2
+
+# Or multilingual
+~/.openclaw/extensions/parakeet-stt/scripts/install.sh v3
+```
+
+This downloads the pre-quantized INT8 model (~475MB) from the [Handy project](https://github.com/cjpais/Handy).
+
+### 3. Configure OpenClaw
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "tools": {
+    "media": {
+      "audio": {
+        "enabled": true,
+        "models": [
+          {
+            "type": "cli",
+            "command": "/home/YOUR_USER/.openclaw/tools/parakeet/parakeet-audio-client.py",
+            "args": ["{{MediaPath}}", "{{OutputDir}}"]
+          }
+        ]
+      }
+    }
+  },
+  "plugins": {
+    "entries": {
+      "parakeet-stt": {
+        "enabled": true,
+        "modelVersion": "v2"
+      }
+    }
+  }
+}
+```
+
+## Switching Models
+
+```bash
+# Switch to V2 (English)
+~/.openclaw/extensions/parakeet-stt/scripts/install.sh v2
+
+# Switch to V3 (Multilingual)
+~/.openclaw/extensions/parakeet-stt/scripts/install.sh v3
+```
+
+The install script updates a symlink, so the daemon automatically uses the new model on next load.
+
+## CLI Commands
+
+```bash
+# Check status
+openclaw parakeet:status
+
+# Install model
+openclaw parakeet:install v2
+```
+
+## Requirements
+
+- Python 3.8+
+- ~500MB disk space for model
+- ~500MB RAM when model loaded
+
+## Credits
+
+- Models: [NVIDIA Parakeet TDT](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v2)
+- INT8 Quantization: [Handy](https://github.com/cjpais/Handy) by cjpais
+- ONNX Runtime for inference
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Parakeet STT Plugin for OpenClaw
+ *
+ * Provides fast CPU-based speech-to-text using Parakeet TDT INT8 models.
+ * Supports V2 (English optimized) and V3 (Multilingual) model selection.
+ *
+ * The actual transcription is configured via tools.media.audio.models in openclaw.json.
+ */
+
+import { Type } from "@sinclair/typebox";
+
+export default function (api: any) {
+  api.logger.info("parakeet-stt: plugin loaded");
+
+  // Register a CLI command for checking Parakeet status
+  api.registerCommand({
+    name: "parakeet:status",
+    description: "Check Parakeet STT daemon status",
+    async handler() {
+      const cfg = api.config.plugins?.entries?.["parakeet-stt"] || {};
+      const modelVersion = cfg.modelVersion || "v2";
+      const toolsDir = `${process.env.HOME}/.openclaw/tools/parakeet`;
+      const modelPath = cfg.modelPath || `${toolsDir}/model`;
+
+      return {
+        modelVersion,
+        modelPath,
+        daemonPath: `${toolsDir}/parakeet-lazy-daemon.py`,
+        enabled: cfg.enabled !== false,
+        timeout: cfg.timeoutMs || 30000,
+        inactivityTimeout: (cfg.inactivityTimeoutMin || 20) + " minutes",
+        installCommand: `bash ~/.openclaw/extensions/parakeet-stt/scripts/install.sh ${modelVersion}`
+      };
+    },
+  });
+
+  // Register a CLI command for installing the model
+  api.registerCommand({
+    name: "parakeet:install",
+    description: "Download and install a Parakeet TDT model",
+    async handler(args: { version?: string }) {
+      const cfg = api.config.plugins?.entries?.["parakeet-stt"] || {};
+      const version = args?.version || cfg.modelVersion || "v2";
+      const installScript = `${process.env.HOME}/.openclaw/extensions/parakeet-stt/scripts/install.sh`;
+      api.logger.info?.(`parakeet-stt: install command called for ${version}`);
+
+      return {
+        message: `Run the install script for ${version}:`,
+        command: `bash ${installScript} ${version}`,
+        hint: "v2 = English optimized, v3 = Multilingual (25 languages)"
+      };
+    },
+  });
+
+  // Register an agent tool for checking transcription status
+  api.registerTool(
+    {
+      name: "parakeet_status",
+      description: "Check the status of the Parakeet speech-to-text system",
+      parameters: Type.Object({}),
+      async execute() {
+        const cfg = api.config.plugins?.entries?.["parakeet-stt"] || {};
+        const modelVersion = cfg.modelVersion || "v2";
+        const modelPath = cfg.modelPath || `${process.env.HOME}/.openclaw/tools/parakeet/model`;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                enabled: cfg.enabled !== false,
+                modelVersion,
+                modelPath,
+                configured: !!cfg.enabled
+              }, null, 2)
+            }
+          ]
+        };
+      },
+    },
+    { optional: true }
+  );
+}

package/openclaw.plugin.json

@@ -0,0 +1,71 @@
+{
+  "id": "parakeet-stt",
+  "name": "Parakeet STT",
+  "description": "Fast CPU-based speech-to-text using Parakeet TDT INT8 models. 4x faster than real-time. Supports V2 (English optimized) and V3 (multilingual).",
+  "version": "0.2.0",
+  "skills": ["skills/parakeet"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "modelVersion": {
+        "type": "string",
+        "enum": ["v2", "v3"],
+        "default": "v2",
+        "description": "Model version: v2 for English (higher accuracy), v3 for multilingual (25 languages, auto-detect)"
+      },
+      "modelPath": {
+        "type": "string",
+        "description": "Path to the Parakeet ONNX model directory (auto-set based on modelVersion)"
+      },
+      "daemonPath": {
+        "type": "string",
+        "description": "Path to the parakeet daemon script"
+      },
+      "timeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "default": 30000,
+        "description": "Timeout for transcription requests"
+      },
+      "inactivityTimeoutMin": {
+        "type": "integer",
+        "minimum": 1,
+        "default": 20,
+        "description": "Minutes of inactivity before unloading the model"
+      }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable Parakeet STT"
+    },
+    "modelVersion": {
+      "label": "Model Version",
+      "help": "v2 = English optimized (higher accuracy), v3 = Multilingual (25 European languages with auto-detect)"
+    },
+    "modelPath": {
+      "label": "Model Path",
+      "placeholder": "~/.openclaw/tools/parakeet/model",
+      "help": "Directory containing the Parakeet ONNX model files",
+      "advanced": true
+    },
+    "daemonPath": {
+      "label": "Daemon Script Path",
+      "placeholder": "~/.openclaw/tools/parakeet/parakeet-lazy-daemon.py",
+      "advanced": true
+    },
+    "timeoutMs": {
+      "label": "Request Timeout (ms)",
+      "advanced": true
+    },
+    "inactivityTimeoutMin": {
+      "label": "Inactivity Timeout (minutes)",
+      "help": "How long before the model unloads to save memory",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@nicfox77/parakeet-stt",
+  "version": "0.2.0",
+  "description": "Parakeet TDT INT8 speech-to-text plugin for OpenClaw. Supports V2 (English) and V3 (Multilingual) models.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nicfox77/openclaw-parakeet-stt.git"
+  },
+  "author": "Nicfox77",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "parakeet",
+    "stt",
+    "speech-to-text",
+    "transcription",
+    "asr",
+    "nvidia"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+# Parakeet TDT INT8 Model Installer
+# Downloads pre-quantized INT8 models from the Handy project
+# https://github.com/cjpais/Handy
+
+set -e
+
+# Configuration
+PARAKEET_DIR="${PARAKEET_DIR:-$HOME/.openclaw/tools/parakeet}"
+VENV_DIR="$PARAKEET_DIR/.venv"
+
+# Model URLs (from Handy project)
+MODEL_URLS_V2="https://blob.handy.computer/parakeet-v2-int8.tar.gz"
+MODEL_URLS_V3="https://blob.handy.computer/parakeet-v3-int8.tar.gz"
+
+# Default to V2 (English optimized)
+VERSION="${1:-v2}"
+
+# Validate version
+if [[ "$VERSION" != "v2" && "$VERSION" != "v3" ]]; then
+    echo "Usage: $0 [v2|v3]"
+    echo "  v2 - English optimized (higher accuracy for English)"
+    echo "  v3 - Multilingual (25 European languages, auto-detect)"
+    exit 1
+fi
+
+# Select URL based on version
+if [[ "$VERSION" == "v2" ]]; then
+    MODEL_URL="$MODEL_URLS_V2"
+    MODEL_DIR="$PARAKEET_DIR/model-v2"
+    MODEL_SIZE="473MB"
+    MODEL_DESC="English optimized"
+else
+    MODEL_URL="$MODEL_URLS_V3"
+    MODEL_DIR="$PARAKEET_DIR/model-v3"
+    MODEL_SIZE="478MB"
+    MODEL_DESC="Multilingual (25 languages)"
+fi
+
+# Create symlink to active model
+ACTIVE_MODEL_LINK="$PARAKEET_DIR/model"
+
+echo "=== Parakeet TDT $VERSION INT8 Installer ==="
+echo "Model: $MODEL_DESC"
+echo ""
+
+# Check Python
+if ! command -v python3 &> /dev/null; then
+    echo "Error: Python 3 is required"
+    exit 1
+fi
+
+echo "Python version: $(python3 --version)"
+
+# Create directories
+mkdir -p "$PARAKEET_DIR"
+
+# Create virtual environment (reuse existing if present)
+if [ ! -d "$VENV_DIR" ]; then
+    echo "Creating Python virtual environment..."
+    python3 -m venv "$VENV_DIR"
+fi
+
+# Activate venv
+source "$VENV_DIR/bin/activate"
+
+# Install minimal dependencies (Handy models just need onnxruntime + librosa)
+echo "Installing Python dependencies..."
+pip install --upgrade pip
+pip install onnxruntime librosa soundfile
+
+# Download and extract model if not present
+if [ ! -d "$MODEL_DIR" ] || [ ! -f "$MODEL_DIR/model.onnx" ]; then
+    echo ""
+    echo "Downloading Parakeet TDT $VERSION model (~$MODEL_SIZE)..."
+    echo "URL: $MODEL_URL"
+    
+    TMP_TAR="/tmp/parakeet-$VERSION-int8.tar.gz"
+    
+    if command -v wget &> /dev/null; then
+        wget -O "$TMP_TAR" "$MODEL_URL"
+    elif command -v curl &> /dev/null; then
+        curl -L -o "$TMP_TAR" "$MODEL_URL"
+    else
+        echo "Error: wget or curl required for download"
+        exit 1
+    fi
+    
+    echo "Extracting model..."
+    mkdir -p "$MODEL_DIR"
+    tar -xzf "$TMP_TAR" -C "$MODEL_DIR" --strip-components=1 2>/dev/null || {
+        # If strip-components fails, try without it
+        tar -xzf "$TMP_TAR" -C "$MODEL_DIR"
+        # Move files from subdirectory if needed
+        for subdir in "$MODEL_DIR"/*/; do
+            if [ -d "$subdir" ]; then
+                mv "$subdir"* "$MODEL_DIR/" 2>/dev/null || true
+                rmdir "$subdir" 2>/dev/null || true
+            fi
+        done
+    }
+    rm -f "$TMP_TAR"
+    
+    echo "Model downloaded and extracted successfully"
+else
+    echo "Model already exists at $MODEL_DIR"
+fi
+
+# Update symlink to active model
+rm -f "$ACTIVE_MODEL_LINK"
+ln -s "$MODEL_DIR" "$ACTIVE_MODEL_LINK"
+echo "Active model symlink: $ACTIVE_MODEL_LINK -> $MODEL_DIR"
+
+# Copy scripts from extension to tools directory
+SCRIPTS_SRC="$HOME/.openclaw/extensions/parakeet-stt/scripts"
+for script in parakeet-lazy-daemon.py parakeet-audio-client.py parakeet_transcribe.py; do
+    if [ -f "$SCRIPTS_SRC/$script" ]; then
+        cp "$SCRIPTS_SRC/$script" "$PARAKEET_DIR/"
+        chmod +x "$PARAKEET_DIR/$script"
+        echo "Copied $script"
+    fi
+done
+
+echo ""
+echo "=== Installation Complete ==="
+echo ""
+echo "Version: $VERSION ($MODEL_DESC)"
+echo "Model directory: $MODEL_DIR"
+echo "Active model: $ACTIVE_MODEL_LINK"
+echo "Virtual environment: $VENV_DIR"
+echo ""
+echo "To switch models, run:"
+echo "  $0 v2  # English optimized"
+echo "  $0 v3  # Multilingual"
+echo ""
+echo "OpenClaw config (already configured):"
+echo '  tools.media.audio.models → parakeet-audio-client.py'

package/scripts/parakeet-audio-client.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+
+SOCKET_PATH = "/tmp/parakeet-lazy.sock"
+DAEMON_PATH = os.path.expanduser("~/.openclaw/tools/parakeet/parakeet-lazy-daemon.py")
+
+def ensure_daemon():
+    # Check if daemon socket exists and responsive
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
+            s.settimeout(0.5)
+            s.connect(SOCKET_PATH)
+        return  # daemon already running
+    except Exception:
+        pass
+    # Start daemon in background
+    try:
+        subprocess.Popen(
+            [sys.executable, DAEMON_PATH],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True
+        )
+        time.sleep(1)  # give it a moment to start
+    except Exception as e:
+        print(f"Failed to start daemon: {e}", file=sys.stderr)
+        sys.exit(1)
+
+def query_daemon(audio_path):
+    for attempt in range(3):
+        try:
+            with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
+                s.connect(SOCKET_PATH)
+                request = {"action": "transcribe", "audio_path": audio_path}
+                s.sendall(json.dumps(request).encode() + b"\n")
+                response_data = b""
+                while True:
+                    chunk = s.recv(4096)
+                    if not chunk:
+                        break
+                    response_data += chunk
+                    if b"\n" in chunk:
+                        break
+            if response_data:
+                response = json.loads(response_data.strip())
+                if "text" in response:
+                    print(response["text"])
+                    return 0
+                else:
+                    print(response.get("error", "Unknown error"), file=sys.stderr)
+                    return 1
+            else:
+                time.sleep(0.5)
+        except Exception as e:
+            if attempt == 2:
+                print(f"Daemon communication failed: {e}", file=sys.stderr)
+                return 1
+            time.sleep(0.5)
+    return 1
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: parakeet-audio-client.py <audio_path> [output_dir]", file=sys.stderr)
+        sys.exit(1)
+    audio_path = sys.argv[1]
+    # output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+    ensure_daemon()
+    sys.exit(query_daemon(audio_path))

package/scripts/parakeet-lazy-daemon.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+Parakeet Lazy Daemon - Loads model on demand, unloads after inactivity.
+Supports V2 (English) and V3 (Multilingual) model selection.
+"""
+import json
+import os
+import signal
+import socket
+import sys
+import time
+from pathlib import Path
+
+# Add script directory to path to import ParakeetTDT
+SCRIPT_DIR = Path(__file__).parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+# Try to import, will fail if model not installed yet
+try:
+    from parakeet_transcribe import ParakeetTDT
+except ImportError:
+    print("Error: parakeet_transcribe not found. Run install.sh first.", file=sys.stderr)
+    sys.exit(1)
+
+SOCKET_PATH = "/tmp/parakeet-lazy.sock"
+IDLE_TIMEOUT = 20 * 60  # 20 minutes
+
+def get_model_path():
+    """Determine which model to use based on config/env."""
+    tools_dir = Path.home() / ".openclaw" / "tools" / "parakeet"
+    
+    # 1. Check for explicit symlink (created by install.sh)
+    symlink = tools_dir / "model"
+    if symlink.is_symlink() or symlink.is_dir():
+        return symlink.resolve()
+    
+    # 2. Check environment variable
+    model_version = os.environ.get("PARAKEET_MODEL_VERSION", "").lower()
+    if model_version in ("v2", "2"):
+        return tools_dir / "model-v2"
+    if model_version in ("v3", "3"):
+        return tools_dir / "model-v3"
+    
+    # 3. Check for installed models, prefer v2 (English)
+    for version in ["v2", "v3"]:
+        model_dir = tools_dir / f"model-{version}"
+        if model_dir.is_dir():
+            return model_dir
+    
+    # 4. Fallback to symlink path (will error if not installed)
+    return symlink
+
+
+class ParakeetLazyDaemon:
+    def __init__(self):
+        self.model_dir = get_model_path()
+        self.transcriber = None
+        self.last_used = None
+        self.running = True
+        
+        # Validate model exists
+        if not self.model_dir.is_dir():
+            print(f"Error: Model not found at {self.model_dir}", file=sys.stderr)
+            print("Run: ~/.openclaw/extensions/parakeet-stt/scripts/install.sh [v2|v3]", file=sys.stderr)
+            sys.exit(1)
+        
+        print(f"Using model: {self.model_dir}", file=sys.stderr)
+        
+        # Clean up any existing socket
+        try:
+            os.unlink(SOCKET_PATH)
+        except OSError:
+            if os.path.exists(SOCKET_PATH):
+                raise
+        
+        self.server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.server.bind(SOCKET_PATH)
+        os.chmod(SOCKET_PATH, 0o666)  # world readable/writable
+        self.server.listen(1)
+        signal.signal(signal.SIGTERM, self._handle_signal)
+        signal.signal(signal.SIGINT, self._handle_signal)
+
+    def _handle_signal(self, signum, frame):
+        self.running = False
+
+    def ensure_loaded(self):
+        if self.transcriber is None:
+            print("Loading Parakeet model...", file=sys.stderr)
+            self.transcriber = ParakeetTDT(str(self.model_dir))
+            print("Model loaded.", file=sys.stderr)
+        self.last_used = time.time()
+
+    def unload_if_idle(self):
+        if self.transcriber is None or self.last_used is None:
+            return
+        idle = time.time() - self.last_used
+        if idle > IDLE_TIMEOUT:
+            print(f"Unloading model (idle {idle:.1f}s)", file=sys.stderr)
+            self.transcriber = None
+            import gc
+            gc.collect()
+
+    def handle_connection(self, conn):
+        response = None
+        try:
+            data = b""
+            while True:
+                chunk = conn.recv(4096)
+                if not chunk:
+                    break
+                data += chunk
+                if b"\n" in chunk:
+                    break
+            if not data:
+                response = {"error": "Empty request"}
+            else:
+                line = data.split(b"\n", 1)[0].strip()
+                request = json.loads(line.decode())
+                action = request.get("action")
+                if action != "transcribe":
+                    response = {"error": f"Unsupported action: {action}"}
+                else:
+                    audio_path = request["audio_path"]
+                    self.ensure_loaded()
+                    audio = self.transcriber.load_audio(audio_path)
+                    text, tokens, timestamps = self.transcriber.transcribe(audio)
+                    self.last_used = time.time()
+                    response = {"text": text, "tokens": tokens, "timestamps": timestamps}
+        except Exception as e:
+            response = {"error": str(e)}
+        finally:
+            if response is not None:
+                conn.sendall(json.dumps(response).encode() + b"\n")
+            conn.close()
+        self.unload_if_idle()
+
+    def run(self):
+        print("ParakeetLazyDaemon listening on", SOCKET_PATH, file=sys.stderr)
+        while self.running:
+            try:
+                conn, addr = self.server.accept()
+                self.handle_connection(conn)
+            except socket.timeout:
+                continue
+            except Exception as e:
+                print("Daemon error:", e, file=sys.stderr)
+                continue  # Keep serving instead of breaking
+        self.server.close()
+        try:
+            os.unlink(SOCKET_PATH)
+        except OSError:
+            pass
+
+if __name__ == "__main__":
+    daemon = ParakeetLazyDaemon()
+    daemon.run()

package/scripts/parakeet_transcribe.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""
+Parakeet TDT V2 INT8 Transcription Script
+Based on transcribe-rs implementation: https://github.com/cjpais/transcribe-rs
+"""
+
+import argparse
+import json
+import time
+import re
+import numpy as np
+from pathlib import Path
+
+import onnxruntime as ort
+import librosa
+
+
+class ParakeetTDT:
+    """Parakeet TDT V2 INT8 transcriber using ONNX Runtime."""
+    
+    # Constants from transcribe-rs
+    SUBSAMPLING_FACTOR = 8
+    WINDOW_SIZE = 0.01
+    MAX_TOKENS_PER_STEP = 10
+    
+    def __init__(self, model_dir: str):
+        model_dir = Path(model_dir)
+        
+        # Load config
+        config_path = model_dir / "config.json"
+        with open(config_path) as f:
+            self.config = json.load(f)
+        
+        # Load vocabulary
+        self.vocab, self.blank_idx = self._load_vocab(model_dir / "vocab.txt")
+        self.vocab_size = len(self.vocab)
+        print(f"Loaded vocabulary: {self.vocab_size} tokens, blank_idx={self.blank_idx}")
+        
+        self.sample_rate = 16000
+        
+        # Create ONNX sessions
+        sess_options = ort.SessionOptions()
+        sess_options.intra_op_num_threads = 4
+        sess_options.inter_op_num_threads = 4
+        sess_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+        
+        print(f"Loading preprocessor...")
+        start = time.time()
+        self.preprocessor = ort.InferenceSession(
+            str(model_dir / "nemo128.onnx"), sess_options)
+        print(f"Preprocessor loaded in {time.time() - start:.2f}s")
+        
+        print(f"Loading encoder...")
+        start = time.time()
+        self.encoder = ort.InferenceSession(
+            str(model_dir / "encoder-model.int8.onnx"), sess_options)
+        print(f"Encoder loaded in {time.time() - start:.2f}s")
+        
+        print(f"Loading decoder...")
+        start = time.time()
+        self.decoder = ort.InferenceSession(
+            str(model_dir / "decoder_joint-model.int8.onnx"), sess_options)
+        print(f"Decoder loaded in {time.time() - start:.2f}s")
+    
+    def _load_vocab(self, vocab_path: Path) -> tuple:
+        """Load vocabulary from vocab.txt file."""
+        vocab = {}
+        blank_idx = 0
+        
+        with open(vocab_path) as f:
+            for line in f:
+                parts = line.rstrip().split(' ')
+                if len(parts) >= 2:
+                    token = parts[0]
+                    # Replace SentencePiece space marker with actual space
+                    token = token.replace('\u2581', ' ')
+                    idx = int(parts[1])
+                    vocab[idx] = token
+                    if token.strip() == '<blk>':
+                        blank_idx = idx
+        
+        return vocab, blank_idx
+    
+    def load_audio(self, audio_path: str) -> np.ndarray:
+        """Load audio file and convert to 16kHz mono float32."""
+        audio, sr = librosa.load(audio_path, sr=self.sample_rate, mono=True)
+        return audio.astype(np.float32)
+    
+    def transcribe(self, audio: np.ndarray) -> tuple:
+        """Transcribe audio using Parakeet TDT model."""
+        # Prepare audio
+        waveforms = audio.reshape(1, -1)
+        waveforms_lens = np.array([audio.shape[0]], dtype=np.int64)
+        
+        # Preprocess (mel spectrogram)
+        start = time.time()
+        prep_out = self.preprocessor.run(
+            None,
+            {'waveforms': waveforms, 'waveforms_lens': waveforms_lens}
+        )
+        features, features_lens = prep_out[0], prep_out[1]
+        print(f"Preprocessor: {time.time() - start:.3f}s, features shape: {features.shape}")
+        
+        # Encode
+        start = time.time()
+        enc_out = self.encoder.run(
+            None,
+            {'audio_signal': features, 'length': features_lens}
+        )
+        encoder_out = enc_out[0]  # [1, 1024, time]
+        encoder_out_lens = enc_out[1]
+        # Transpose to [1, time, 1024] like transcribe-rs
+        encoder_out = encoder_out.transpose(0, 2, 1)
+        print(f"Encoder: {time.time() - start:.3f}s, encoded shape: {encoder_out.shape}")
+        
+        # Decode
+        start = time.time()
+        tokens, timestamps = self._decode_sequence(
+            encoder_out[0], int(encoder_out_lens[0]))
+        decode_time = time.time() - start
+        print(f"Decode: {decode_time:.3f}s")
+        
+        # Convert to text
+        text = self._decode_tokens(tokens)
+        
+        return text, tokens, timestamps
+    
+    def _create_decoder_state(self) -> tuple:
+        """Create initial decoder state (LSTM hidden states)."""
+        # Shape: [2, 1, 640] for batch_size=1
+        state1 = np.zeros((2, 1, 640), dtype=np.float32)
+        state2 = np.zeros((2, 1, 640), dtype=np.float32)
+        return state1, state2
+    
+    def _decode_step(self, prev_tokens: list, prev_state: tuple, 
+                     encoder_step: np.ndarray) -> tuple:
+        """Run one decoder step.
+        
+        Args:
+            prev_tokens: Previously emitted tokens
+            prev_state: Previous decoder state (state1, state2)
+            encoder_step: Encoder output for current frame [1024]
+        
+        Returns:
+            (logits, new_state)
+        """
+        # Get last token or blank if empty
+        target_token = prev_tokens[-1] if prev_tokens else self.blank_idx
+        
+        # Prepare inputs
+        # encoder_outputs: [1, 1024, 1] (batch, dim, time) - matches ONNX input shape
+        encoder_outputs = encoder_step.reshape(1, -1, 1).astype(np.float32)
+        targets = np.array([[target_token]], dtype=np.int32)
+        target_length = np.array([1], dtype=np.int32)  # Must be int32 for this model
+        state1, state2 = prev_state
+        
+        outputs = self.decoder.run(
+            None,
+            {
+                'encoder_outputs': encoder_outputs,
+                'targets': targets,
+                'target_length': target_length,
+                'input_states_1': state1,
+                'input_states_2': state2,
+            }
+        )
+        
+        logits = outputs[0]  # [1, 1, vocab_size + duration]
+        new_state1 = outputs[2]
+        new_state2 = outputs[3]
+        
+        return logits[0, 0], (new_state1, new_state2)
+    
+    def _decode_sequence(self, encodings: np.ndarray, 
+                         encodings_len: int) -> tuple:
+        """Decode encoded sequence using greedy algorithm.
+        
+        Implements TDT decoding with MAX_TOKENS_PER_STEP limit.
+        """
+        prev_state = self._create_decoder_state()
+        tokens = []
+        timestamps = []
+        
+        t = 0
+        emitted_tokens = 0
+        
+        while t < encodings_len:
+            encoder_step = encodings[t]  # [1024]
+            logits, new_state = self._decode_step(tokens, prev_state, encoder_step)
+            
+            # For TDT: split into vocab logits and duration logits
+            if len(logits) > self.vocab_size:
+                vocab_logits = logits[:self.vocab_size]
+                # Duration logits not used in basic greedy decoding
+            else:
+                vocab_logits = logits
+            
+            # Get argmax token
+            token = int(np.argmax(vocab_logits))
+            
+            # Process non-blank token
+            if token != self.blank_idx:
+                prev_state = new_state
+                tokens.append(token)
+                timestamps.append(t)
+                emitted_tokens += 1
+            
+            # Advance frame on blank OR after max tokens per step
+            if token == self.blank_idx or emitted_tokens == self.MAX_TOKENS_PER_STEP:
+                t += 1
+                emitted_tokens = 0
+        
+        return tokens, timestamps
+    
+    def _decode_tokens(self, ids: list) -> str:
+        """Convert token IDs to text."""
+        tokens = []
+        for token_id in ids:
+            if token_id < len(self.vocab):
+                token = self.vocab[token_id]
+                # SentencePiece uses '▁' (U+2581) to mark word starts
+                # Replace with space for proper word separation
+                if token.startswith(' '):
+                    tokens.append(token)  # Already has leading space
+                else:
+                    tokens.append(token)
+        
+        # Join all tokens - spaces are already embedded
+        text = ''.join(tokens)
+        
+        # Clean up multiple spaces
+        text = re.sub(r' +', ' ', text)
+        
+        return text.strip()
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Parakeet TDT V2 INT8 Transcription')
+    parser.add_argument('audio', help='Path to audio file')
+    parser.add_argument('--model', default='~/.openclaw/models/parakeet-tdt-0.6b-v2-int8',
+                       help='Path to model directory')
+    args = parser.parse_args()
+    
+    model_path = Path(args.model).expanduser()
+    audio_path = args.audio
+    
+    print(f"Loading model from {model_path}...")
+    transcriber = ParakeetTDT(model_path)
+    
+    print(f"\nLoading audio from {audio_path}...")
+    audio = transcriber.load_audio(audio_path)
+    duration = len(audio) / transcriber.sample_rate
+    print(f"Audio duration: {duration:.2f}s")
+    
+    print("\nTranscribing...")
+    start = time.time()
+    text, tokens, timestamps = transcriber.transcribe(audio)
+    total_time = time.time() - start
+    
+    print(f"\n{'='*60}")
+    print(f"TRANSCRIPTION:")
+    print(f"{text}")
+    print(f"{'='*60}")
+    print(f"\nPerformance:")
+    print(f"  Total time: {total_time:.3f}s")
+    print(f"  Real-time factor: {total_time / duration:.2f}x")
+
+
+if __name__ == '__main__':
+    main()

package/skills/parakeet/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: parakeet
+description: Parakeet speech-to-text system. Provides fast CPU-based transcription using Parakeet TDT INT8 models. Use when checking transcription status or troubleshooting audio issues.
+---
+
+# Parakeet STT
+
+Fast CPU-based speech-to-text using NVIDIA's Parakeet TDT INT8 models.
+
+## Model Versions
+
+| Version | Description | Languages |
+|---------|-------------|-----------|
+| **V2** | English optimized | English (higher accuracy) |
+| **V3** | Multilingual | 25 European languages + auto-detect |
+
+## Install / Switch Model
+
+```bash
+# Install V2 (English optimized - default)
+~/.openclaw/extensions/parakeet-stt/scripts/install.sh v2
+
+# Install/switch to V3 (Multilingual)
+~/.openclaw/extensions/parakeet-stt/scripts/install.sh v3
+```
+
+The install script:
+- Downloads the pre-quantized INT8 model (~475MB)
+- Sets up the Python virtual environment
+- Creates a symlink at `~/.openclaw/tools/parakeet/model` pointing to the active model
+
+## Status Check
+
+```bash
+openclaw parakeet:status
+```
+
+## How It Works
+
+1. Audio messages are automatically transcribed before reaching the agent
+2. First transcription loads the model (~3 seconds)
+3. Model stays loaded for subsequent transcriptions
+4. After 20 minutes of inactivity, model unloads to save memory
+
+## Model Selection
+
+The daemon automatically selects the model:
+
+1. **Symlink** (`~/.openclaw/tools/parakeet/model`) - set by install.sh
+2. **Environment variable** `PARAKEET_MODEL_VERSION=v2` or `v3`
+3. **Auto-detect** - looks for model-v2, then model-v3 directories
+
+## Troubleshooting
+
+### Check if configured
+
+Look at `tools.media.audio.models` in openclaw.json - it should point to the parakeet client script.
+
+### Check daemon status
+
+```bash
+# Check if daemon socket exists
+ls -la /tmp/parakeet-lazy.sock
+
+# Watch logs
+openclaw logs --follow | grep -i parakeet
+```
+
+### Model not found error
+
+Run the install script:
+```bash
+~/.openclaw/extensions/parakeet-stt/scripts/install.sh v2
+```
+
+### Manual transcription test
+
+```bash
+# Activate venv and test
+source ~/.openclaw/tools/parakeet/venv/bin/activate
+python ~/.openclaw/tools/parakeet/parakeet_transcribe.py path/to/audio.ogg
+```
+
+## Configuration
+
+In `plugins.entries.parakeet-stt`:
+- `enabled`: Enable/disable
+- `modelVersion`: "v2" or "v3" (informational - actual switching via install.sh)
+- `inactivityTimeoutMin`: Minutes before unloading (default: 20)