Handy API调用示例：Python/JavaScript集成代码-优快云博客

Handy API调用示例：Python/JavaScript集成代码

【免费下载链接】Handy A free, open source, and extensible speech-to-text application that works completely offline. 项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy

你是否正在寻找一款完全离线的语音转文字解决方案？Handy作为开源离线语音识别工具，提供了丰富的API接口，让开发者能够轻松集成语音识别功能到自己的应用中。本文将详细介绍Handy的API调用方法，并提供Python和JavaScript的集成示例，帮助你快速上手。

API概述

Handy的API系统基于Tauri框架构建，通过Rust后端提供核心功能，并通过前端JavaScript API暴露给用户。主要API分布在以下文件中：

Rust命令定义：src-tauri/src/commands/mod.rs
模型管理API：src-tauri/src/commands/models.rs
转录功能API：src-tauri/src/commands/transcription.rs
前端API封装：src/hooks/useModels.ts

Handy API主要分为三大类：模型管理、语音转录和系统设置。所有API调用都通过Tauri的invoke函数实现，确保安全的跨进程通信。

前置条件

在开始集成Handy API之前，请确保：

已安装Handy应用
已下载至少一个语音模型（推荐使用默认的"parakeet-tdt-0.6b-v3"模型）
对于JavaScript集成，需要导入Tauri的invoke函数：

import { invoke } from "@tauri-apps/api/core";

模型管理API

模型管理是Handy的核心功能之一，允许你下载、选择和管理语音识别模型。以下是常用的模型管理API及其使用示例。

获取可用模型列表

获取所有可用的语音模型，包括已下载和可下载的模型：

// JavaScript示例
import { invoke } from "@tauri-apps/api/core";

async function getAvailableModels() {
  try {
    const models = await invoke("get_available_models");
    console.log("可用模型:", models);
    return models;
  } catch (error) {
    console.error("获取模型失败:", error);
  }
}

# Python示例
import json
import subprocess

def get_available_models():
    result = subprocess.run(
        ["handy-cli", "invoke", "get_available_models"],
        capture_output=True, text=True
    )
    if result.returncode == 0:
        return json.loads(result.stdout)
    else:
        print(f"获取模型失败: {result.stderr}")
        return None

下载模型

下载指定ID的语音模型：

// JavaScript示例
async function downloadModel(modelId) {
  try {
    // 开始下载
    await invoke("download_model", { modelId });
    
    // 监听下载进度
    const unlisten = await listen("model-download-progress", (event) => {
      const progress = event.payload;
      console.log(`下载进度: ${progress.percentage}%`);
      
      if (progress.percentage === 100) {
        unlisten(); // 下载完成后取消监听
      }
    });
  } catch (error) {
    console.error("下载模型失败:", error);
  }
}

// 使用示例：下载推荐的第一个模型
downloadModel("parakeet-tdt-0.6b-v3");

设置活动模型

选择并加载指定模型作为当前活动模型：

// JavaScript示例
async function setActiveModel(modelId) {
  try {
    await invoke("set_active_model", { modelId });
    console.log(`已激活模型: ${modelId}`);
  } catch (error) {
    console.error("激活模型失败:", error);
  }
}

语音转录API

语音转录是Handy的核心功能，提供离线语音识别能力。以下是转录相关的API使用示例。

获取模型加载状态

检查当前模型是否已加载：

// JavaScript示例
async function checkModelStatus() {
  try {
    const status = await invoke("get_model_load_status");
    console.log("模型状态:", status);
    return status;
  } catch (error) {
    console.error("获取模型状态失败:", error);
  }
}

手动卸载模型

当不需要语音识别时，可以手动卸载模型释放内存：

// JavaScript示例
async function unloadModel() {
  try {
    await invoke("unload_model_manually");
    console.log("模型已卸载");
  } catch (error) {
    console.error("卸载模型失败:", error);
  }
}

系统设置API

Handy提供了多种系统设置API，允许你自定义应用行为。

设置模型卸载超时

配置模型自动卸载的超时时间：

// JavaScript示例
async function setModelUnloadTimeout(timeout) {
  try {
    await invoke("set_model_unload_timeout", { timeout });
    console.log(`模型卸载超时已设置为: ${timeout}`);
  } catch (error) {
    console.error("设置超时失败:", error);
  }
}

// 使用示例：设置5分钟超时
setModelUnloadTimeout({ minutes: 5 });

获取应用数据目录

获取Handy存储数据的目录路径：

# Python示例
def get_app_data_dir():
    result = subprocess.run(
        ["handy-cli", "invoke", "get_app_dir_path"],
        capture_output=True, text=True
    )
    if result.returncode == 0:
        return result.stdout.strip()
    else:
        print(f"获取目录失败: {result.stderr}")
        return None

完整集成示例

以下是一个完整的JavaScript集成示例，展示如何下载模型、激活模型并检查状态：

import { invoke } from "@tauri-apps/api/core";
import { listen } from "@tauri-apps/api/event";

async function setupHandy() {
  try {
    // 检查是否有可用模型
    const hasModels = await invoke("has_any_models_available");
    
    if (!hasModels) {
      console.log("没有可用模型，正在下载推荐模型...");
      
      // 获取推荐模型
      const recommendedModel = await invoke("get_recommended_first_model");
      
      // 下载模型并监听进度
      const unlistenProgress = await listen("model-download-progress", (event) => {
        const progress = event.payload;
        console.log(`下载进度: ${progress.percentage}%`);
      });
      
      // 开始下载
      await invoke("download_model", { modelId: recommendedModel });
      
      // 等待下载完成
      await new Promise(resolve => {
        const unlistenComplete = listen("model-download-complete", () => {
          unlistenProgress.then(fn => fn());
          unlistenComplete.then(fn => fn());
          resolve();
        });
      });
      
      console.log("模型下载完成");
    }
    
    // 获取当前模型
    const currentModel = await invoke("get_current_model");
    console.log("当前模型:", currentModel);
    
    // 如果没有当前模型，设置推荐模型为活动模型
    if (!currentModel) {
      const recommendedModel = await invoke("get_recommended_first_model");
      await invoke("set_active_model", { modelId: recommendedModel });
      console.log("已激活推荐模型:", recommendedModel);
    }
    
    // 检查模型加载状态
    const status = await invoke("get_model_load_status");
    console.log("模型状态:", status);
    
    return { success: true, currentModel: status.current_model };
  } catch (error) {
    console.error("Handy设置失败:", error);
    return { success: false, error };
  }
}

// 初始化Handy
setupHandy().then(result => {
  if (result.success) {
    console.log("Handy初始化成功，当前模型:", result.currentModel);
    // 在这里开始使用语音识别功能
  }
});

API错误处理最佳实践

在集成Handy API时，建议遵循以下错误处理最佳实践：

始终使用try/catch捕获异常 - API调用可能因网络问题、模型缺失或权限问题而失败
监听事件而非轮询 - 对于长时间运行的操作（如下载），使用事件监听获取进度更新
检查模型状态 - 在执行转录前，确保模型已加载
处理大文件下载 - 模型文件可能较大，确保有足够的磁盘空间

总结

Handy提供了强大而灵活的API，使开发者能够轻松集成离线语音识别功能。本文介绍了主要API的使用方法，包括模型管理、语音转录和系统设置，并提供了Python和JavaScript的示例代码。

通过这些API，你可以构建各种语音识别应用，从简单的语音转文字工具到复杂的语音控制应用。Handy的离线特性使其特别适合对隐私和网络连接有严格要求的场景。

要了解更多API详情，请查看源代码中的命令定义：src-tauri/src/commands/

祝你在Handy集成之旅中取得成功！

【免费下载链接】Handy A free, open source, and extensible speech-to-text application that works completely offline. 项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考