@eka-care/ekascribe-ts-sdk

中文文档
3.0.58发布于 2026/10/22MITTypeScriptES Module近 30 天下载 1956

EkaScribe TypeSDK - 现代ES2020建设

中文使用文档
文档目录55 节
  1. 先决条件
  2. 安装
  3. Bundler 设置
  4. 维特
  5. 网页包 5
  6. 下一个.js
  7. 浏览器( 脚本标签)
  8. 实例管理
  9. 融合指南
  10. 步骤1:初始化 SDK
  11. 第2步:登记召回
  12. 第3步:开始录音
  13. 第4步:暂停/恢复
  14. 第5步:结束记录
  15. 步骤6:获取输出
  16. 步骤7:清理
  17. 流程图
  18. 回调引用
  19. onTokenRequired
  20. onRecordingStateChange
  21. onAudioEvent
  22. onUploadEvent
  23. onSessionEvent
  24. onError
  25. 删除回调
  26. 重试上传失败
  27. 取消会话
  28. 预录音频上传
  29. 会话 Utils
  30. getSessionHistory(request)
  31. getSessionDetails(request)
  32. getDocument(documentId)
  33. patchSessionStatus(request, sessionId?)
  34. 发现
  35. getDiscoveryDocument()
  36. getDiscoveryConfig()
  37. 部件
  38. 一体化
  39. 行为
  40. 部件状态流程
  41. 类型
  42. 认证
  43. updateAuthTokens(token)
  44. 共享工人配置
  45. 设置
  46. 错误代码
  47. 折旧方法
  48. initTransaction(request)
  49. startRecording(microphoneID?)
  50. getTemplateOutput(request)
  51. getOutputTranscription(request)
  52. commitTransactionCall()
  53. stopTransactionCall()
  54. 完整示例
  55. 贡献准则

EkaScribe 类型脚本 SDK

浏览器SDK用于使用Eka Care的语音转录API来捕捉音频并生成结构化的医疗文件.

先决条件

  • 节点14+
  • npm 或者说 yarn
  • 通过浏览器权限访问麦克风
  • 稳定的网络连接
  • 从Eka Care处获得信使

安装

npm install @eka-care/ekascribe-ts-sdk
# or
yarn add @eka-care/ekascribe-ts-sdk

Bundler 设置

SDK使用共享工作器进行背景音频上传. 现代捆绑者自动处理这个.

维特

工作在盒子内.

import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';

网页包 5

工作在盒子内。 这个 new URL(..., import.meta.url) 模式为本地支持.

import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';

下一个.js

确保 SDK 只用于客户端 :

'use client';

import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';

浏览器( 脚本标签)

<script type="module">
  import { getEkaScribeInstance } from 'https://cdn.jsdelivr.net/npm/@eka-care/ekascribe-ts-sdk/dist/index.mjs';
</script>

实例管理

SDK使用一个 单子图案。 。 。 . getEkaScribeInstance() 总是返回给定的同一实例 env + 键 clientId 组合.

const ekascribe = getEkaScribeInstance(config);
  • 通话 getEkaScribeInstance() 多次使用相同的配置返回同一实例.
  • 若为 env 或者说 clientId 更改,将自动重置旧实例.
  • 如果只是这样的话 access_token 更改,在不重置的情况下将符号更新到已有实例上.
  • SDK 支持 一次进行中的记录。总是打电话 endRecording() 或者说 cancelSession() 在开始新的录音之前。 如果你打电话 startRecordingV2() 当录制活动时, SDK 在本地清理旧录制, 但确实 没有 结束服务器上的会话 —— 旧会话将被丢弃直到到期 .

融合指南

步骤1:初始化 SDK

import { getEkaScribeInstance } from '@eka-care/ekascribe-ts-sdk';
import type { EkaScribeConfig } from '@eka-care/ekascribe-ts-sdk';

const config: EkaScribeConfig = {
  access_token: '<your_access_token>',
  env: 'PROD',                             // 'PROD' | 'DEV'
  clientId: '<your_client_id>',            // optional
  allianceConfig: {
    baseUrl: 'https://api.eka.care/voice/v1',  // required
    useWorker: 'auto',                              // optional: true | false | 'auto'
    debug: false,                                   // optional
  },
  sharedWorkerUrl: workerUrl,              // optional — see SharedWorker section
};

const ekascribe = getEkaScribeInstance(config);

EkaScribeConfig

interface EkaScribeConfig {
  access_token?: string;          // Bearer token for authentication
  env: 'PROD' | 'DEV';           // Environment
  clientId?: string;              // Your client identifier
  mode?: 'http' | 'ipc';         // Transport mode (default: 'http')
  ipcBridge?: IpcBridge;          // Required when mode is 'ipc' (Electron apps)
  enableTracking?: boolean;       // Enable internal analytics tracking
  flavour?: string;               // Client flavour identifier
  sharedWorkerUrl?: string;       // URL to worker.bundle.js for background uploads
  allianceConfig?: {
    baseUrl?: string;             // Scribe service URL (required)
    useWorker?: boolean | 'auto'; // SharedWorker: true | false | 'auto' (default: 'auto')
    debug?: boolean;              // Enable debug logging (default: false)
  };
  widget?: WidgetConfig;          // Widget configuration — see Widget section
}

第2步:登记召回

注册回调 在此之前 开始录制。 事件一开始就起火.

import type { EkaCallbackMap } from '@eka-care/ekascribe-ts-sdk';

// Token refresh — SDK calls this automatically on 401
ekascribe.registerCallback('onTokenRequired', async () => {
  const newToken = await fetchFreshToken(); // your token refresh logic
  return newToken; // must return the new token string
});

// Recording state changes
ekascribe.registerCallback('onRecordingStateChange', (event) => {
  console.log('State:', event.type); // 'started' | 'paused' | 'resumed' | 'ended'
});

// Upload progress
ekascribe.registerCallback('onUploadEvent', (event) => {
  if (event.type === 'progress') {
    console.log(`Uploaded ${event.data.successCount}/${event.data.totalCount}`);
  }
});

// Errors
ekascribe.registerCallback('onError', (event) => {
  console.error(`[${event.error.code}] ${event.error.message}`);
});

见 回调引用 所有召回类型和有效载荷.

第3步:开始录音

创建会话并在一个电话中启动麦克风 .

import type { RecordingOptions } from '@eka-care/ekascribe-ts-sdk';

const options: RecordingOptions = {
  templates: ['template-id'],             // required: template IDs for output
  sessionMode: 'consultation',            // optional: 'consultation' | 'dictation'
  languageHint: ['en', 'hi'],            // optional: input audio language hints
  transcriptLanguage: 'en',              // optional: output transcript language
  model: 'pro',                          // optional: 'pro' | 'lite'
  uploadType: 'chunked',                 // optional: 'chunked' (default) | 'single'
  deviceId: microphoneId,                // optional: specific microphone device ID
  patientDetails: {                      // optional
    name: 'John Doe',
    age: '45',
    gender: 'male',
  },
  additionalData: {},                    // optional: any extra data for the session
};

const result = await ekascribe.startRecordingV2(options);

if (result.error_code) {
  console.error(result.error_code, result.message);
  return;
}

const sessionId = result.txn_id;
console.log('Recording started:', sessionId);

RecordingOptions

interface RecordingOptions {
  templates: string[];                   // Template IDs for extraction (required)
  model?: string;                        // Model ID ('pro' | 'lite')
  languageHint?: string[];               // Language codes for audio input
  transcriptLanguage?: string;           // Language code for transcript output
  uploadType?: string;                   // 'chunked' | 'single' (default: 'chunked')
  communicationProtocol?: string;        // 'http' (default)
  additionalData?: Record<string, any>;  // Extra data for the session
  deviceId?: string;                     // Specific microphone device ID
  sessionMode?: string;                  // 'consultation' | 'dictation'
  patientDetails?: PatientDetails;       // Patient info
  sessionId?: string;                    // External session/transaction ID
}

interface PatientDetails {
  oid?: string;
  name?: string;
  age?: string;
  gender?: string;
  mobile?: number;
}

回应: TStartRecordingResponse

type TStartRecordingResponse = {
  error_code?: ERROR_CODE;  // present only on error
  status_code: number;
  message: string;
  txn_id?: string;          // session ID — present on success
  business_id?: string;
  oid?: string;
  uuid?: string;
};

第4步:暂停/恢复

const pauseResult = ekascribe.pauseRecording();
// later...
const resumeResult = ekascribe.resumeRecording();

回应: TPauseRecordingResponse

type TPauseRecordingResponse = {
  status_code: number;
  message: string;
  error_code?: ERROR_CODE;
  is_paused?: boolean;
};

第5步:结束记录

停止麦克风,冲出待发音频,等待所有上传,并在服务器上结束会话(触发处理).

const endResult = await ekascribe.endRecording();

if (endResult.error_code) {
  switch (endResult.error_code) {
    case 'audio_upload_failed':
      // Some audio files failed to upload — retry
      await ekascribe.retryUploadRecording();
      break;
    case 'end_recording_failed':
    case 'internal_server_error':
      console.error(endResult.error_code, endResult.message);
      break;
  }
}

回应: TEndRecordingResponse

type TEndRecordingResponse = {
  error_code?: ERROR_CODE;
  status_code: number;
  message: string;
  failed_files?: string[];       // files that failed to upload
  total_audio_files?: string[];  // all audio files generated
};

步骤6:获取输出

使用 getSessionStatus() 在结束录制后进行结果调查.

const status = await ekascribe.getSessionStatus(sessionId, {
  poll: {
    maxAttempts: 60,
    intervalMs: 2000,
    signal: abortController.signal,   // optional: cancel polling early
    onProgress: (sessionData) => {
      console.log('Status:', sessionData.status);
      // Display partial results as they come in
      if (sessionData.templates) {
        console.log('Templates:', sessionData.templates);
      }
    },
  },
});

if (status.success) {
  console.log('Final status:', status.data.status);
  console.log('Templates:', status.data.templates);
  console.log('Transcript:', status.data.transcript);
}

回应: SDKResult<GetSessionStatusResponse>

// All async Alliance methods return SDKResult — check result.success
type SDKResult<T> =
  | { success: true; data: T; httpStatus?: number }
  | { success: false; error: ScribeError };

type GetSessionStatusResponse = {
  session_id: string;
  status: SessionStatus;
  created_at: string;
  expires_at?: string | null;
  completed_at?: string | null;
  model_used?: string | null;
  language_detected?: string | null;
  audio_files_received: number;
  audio_files: string[];
  audio_files_processed?: number;
  additional_data: Record<string, any>;
  templates?: TemplateEntry[];
  transcript?: string;
  processing_errors?: ProcessingError[];
  error?: { code: string; message: string };
};

步骤7:清理

// Reset the singleton — clears all state, destroys widget, removes callbacks
await ekascribe.resetInstance();

打电话后 resetInstance()你必须打电话 getEkaScribeInstance() 再次获得一个新的实例.

流程图

  getEkaScribeInstance(config)
         |
         v
  registerCallback()  ──  Set up event handlers before recording
         |
         v
  startRecordingV2()  ──  Creates session + starts mic + begins upload
         |
    pause / resume    ──  Optional during recording
         |
         v
  endRecording()      ──  Stops mic + flushes audio + ends session
         |
         v
  getSessionStatus()  ──  Poll until completed/failed
         |
         v
  Read results        ──  templates, transcript, errors

回调引用

注册 registerCallback(name, handler)。删除方式 removeCallback(name, handler)。 。 。 .

onTokenRequired

当SDK收到来自任何API呼叫的401时自动调用. 您的操作员必须返回一个新的访问标志。 SDK会更新其内部的代号并重试失败的请求.

ekascribe.registerCallback('onTokenRequired', async () => {
  // Call your auth service to get a fresh token
  const newToken = await myAuthService.refreshToken();
  return newToken; // return the token string
});

重要内容:

  • 处理者必须返回 Promise<string> 或者说 string
  • 10秒后SDK出局——如果你的刷新需要更长的时间,请求失败
  • 信使一回,SDK就会打电话 updateAuthTokens() 内部,你不需要自己称呼它
  • 这将取代手动检查的旧模式 status_code: 401 在每次答复中

类型

// Consumer-facing type (EkaScribe SDK)
onTokenRequired: () => Promise<string> | string;

onRecordingStateChange

记录状态过渡时被放出.

ekascribe.registerCallback('onRecordingStateChange', (event) => {
  console.log(event.type); // 'started' | 'paused' | 'resumed' | 'ended'
});

类型

interface RecordingStateChangeEvent {
  type: 'started' | 'paused' | 'resumed' | 'ended';
  timestamp: string;
  data?: any;
}

onAudioEvent

用于语音检测、沉默警告、块创建和帧处理.

ekascribe.registerCallback('onAudioEvent', (event) => {
  switch (event.type) {
    case 'user_speech':
      console.log('Speaking:', event.data.isSpeaking);
      break;
    case 'silence_warning':
      console.log('Silence duration:', event.data.durationMs, 'ms');
      break;
    case 'chunk_ready':
      console.log('Chunk:', event.data.fileName);
      break;
    case 'frame_processed':
      // Raw audio frame data
      break;
  }
});

类型

type AudioEvent =
  | { type: 'user_speech'; timestamp: string; data: { isSpeaking: boolean } }
  | { type: 'silence_warning'; timestamp: string; data: { durationMs: number } }
  | { type: 'chunk_ready'; timestamp: string; data: { chunkIndex: number; fileName: string; chunkData: Uint8Array[] } }
  | { type: 'frame_processed'; timestamp: string; data: { isSpeech: number; notSpeech: number; frame: Float32Array; duration: number } };

onUploadEvent

为上传进度、失败和重试而解雇.

ekascribe.registerCallback('onUploadEvent', (event) => {
  switch (event.type) {
    case 'progress':
      console.log(`${event.data.successCount}/${event.data.totalCount} uploaded`);
      break;
    case 'failed':
      console.error(`Upload failed: ${event.data.fileName}`, event.data.error);
      break;
    case 'retry':
      console.log(`Retrying ${event.data.fileName}, attempt ${event.data.attempt}`);
      break;
  }
});

类型

type UploadEvent =
  | { type: 'progress'; timestamp: string; data: { successCount: number; totalCount: number } }
  | { type: 'failed'; timestamp: string; data: { fileName: string; error: string } }
  | { type: 'retry'; timestamp: string; data: { fileName: string; attempt: number } };

onSessionEvent

在会话生命周期活动时被发射.

ekascribe.registerCallback('onSessionEvent', (event) => {
  switch (event.type) {
    case 'created':
      console.log('Session created:', event.data.session_id);
      break;
    case 'ended':
      console.log('Session ended:', event.data.session_id);
      break;
    case 'status_update':
      console.log('Status update:', event.data.status);
      break;
    case 'partial_result':
      console.log('Partial result:', event.data);
      break;
  }
});

类型

type SessionEvent =
  | { type: 'created'; timestamp: string; data: CreateSessionResponse }
  | { type: 'ended'; timestamp: string; data: EndSessionResponse }
  | { type: 'status_update'; timestamp: string; data: GetSessionStatusResponse }
  | { type: 'partial_result'; timestamp: string; data: any };

onError

SDK出错——VAD故障,工人出错,网络问题,验证出错.

ekascribe.registerCallback('onError', (event) => {
  console.error(`[${event.type}] ${event.error.code}: ${event.error.message}`);
});

类型

interface ErrorEvent {
  type: 'vad_error' | 'worker_error' | 'transport_error' | 'validation_error';
  timestamp: string;
  error: {
    code: string;
    message: string;
    details?: any;
  };
}

删除回调

const handler = (event) => { /* ... */ };

ekascribe.registerCallback('onUploadEvent', handler);
// later...
ekascribe.removeCallback('onUploadEvent', handler);

重试上传失败

若为 endRecording() 返回时 audio_upload_failed,重试失败的上传:

const result = await ekascribe.retryUploadRecording();

回应: TEndRecordingResponse

{
  status_code: number;
  message: string;
  error_code?: ERROR_CODE;
  failed_files?: string[];       // files still failing after retry
  total_audio_files?: string[];
}

取消会话

取消会话 无 启动服务器侧处理.

// Cancel current active session
await ekascribe.cancelSession();

// Or cancel a specific session by ID
await ekascribe.cancelSession('session-id');

回应: SDKResult<PatchSessionResponse>

const result = await ekascribe.cancelSession();
if (result.success) {
  console.log('Session cancelled');
}

预录音频上传

上传一个预先录制的音频文件,而不是现场录制. 用于非实时流量 .

流量 :

  1. 通过 ekascribe.sessions.createSession()
  2. 通过上传音频 processPreRecordedAudio()
  3. 结束会话通过 ekascribe.sessions.endSession()
const result = await ekascribe.processPreRecordedAudio({
  uploadUrl: session.upload_url,       // from createSession response
  audioFile: audioBlob,                // File or Blob
});

请求

{
  uploadUrl: string;        // S3 upload URL from session
  audioFile: File | Blob;   // the audio file
}

回应: TStartRecordingResponse

{
  status_code: number;
  message: string;
  error_code?: ERROR_CODE;
}

会话 Utils

getSessionHistory(request)

获取以前的会话 .

const sessions = await ekascribe.sessions.getSessionHistory({
  txn_count: 10,        // number of sessions to fetch
  oid: 'patient-oid',        // optional: filter by patient oid
});

回应: TGetTransactionHistoryResponse

{
  data: Array<{
    txn_id: string;
    b_id: string;
    created_at: string;
    mode: string;
    oid: string;
    patient_details?: TPatientDetails;
    processing_status: 'success' | 'system_failure' | 'request_failure' | 'cancelled' | 'in-progress';
    user_status: 'init' | 'commit';
    uuid: string;
  }>;
  status: string;
  code: number;
  message: string;
  retrieved_count: number;
}

getSessionDetails(request)

获取特定会话的详细信息,包括文件、上下文和预先签名的URL.

const details = await ekascribe.sessions.getSessionDetails({
  session_id: 'session-id',
  presigned: true,         // include presigned URLs for documents
});

答复中的每一文件都载有: presigned_url。要获取实际文件内容(注释、记录等),请从此 URL 中获取:

const doc = details.data?.documents[0];
if (doc?.presigned_url) {
  const response = await fetch(doc.presigned_url);
  const content = await response.json();
}

指定 URL 是临时的 —— 检查 presigned_url_expires_at (时间戳)使用前。 打电话 getDocument(documentId) 以获取新预签名的 URL,如果过期.

请求

type TGetV1SessionDetailsRequest = {
  session_id: string;
  presigned?: boolean;   // default: false
};

回应: TGetV1SessionDetailsResponse

type TGetV1SessionDetailsResponse = {
  data?: {
    schema_version: string;
    session_id: string;
    uuid: string;
    wid: string;
    created_at: number;
    expires_at: number;
    upload_url: string;
    status: string;
    user_status: 'init' | 'recording_started' | 'commit' | string;
    transfer: string;
    flavour: string;
    patient_details: TPatientDetails | Record<string, unknown>;
    audio_matrix: Record<string, unknown>;
    additional_data: {
      input_languages?: { id: string; name: string }[];
      output_format_template?: {
        template_id: string;
        template_name?: string;
        template_type?: string;
      }[];
      [key: string]: unknown;
    };
    documents: Array<{
      document_id: string;
      session_id: string;
      template_id: string;
      document_name: string;
      document_type: 'notes' | 'context' | 'transcript' | 'integration';
      type: string;
      status: string;
      errors: Array<{ type: string | null; code: string; msg: string }>;
      warnings: Array<{ type: string | null; code: string; msg: string }>;
      publish: Record<string, unknown>;
      created_at: number;
      presigned_url: string | null;
      presigned_url_expires_at: number | null;
      vault_doc_id: string | null;
      lang?: string;
    }>;
    context: {
      past_sessions?: Array<{ date_epoch: number; session_id: string }>;
      documents?: string[];
      attachments?: Array<{ id: string; patient_oid?: string }>;
    };
  };
  status_code: number;
  message?: string;
};

getDocument(documentId)

通过ID获取单一文档 。 如果前一个 URL 已过期, 请使用此选项获取新预签名的 URL .

const doc = await ekascribe.documents.getDocument('document-id');
if (doc.data?.presigned_url) {
  const response = await fetch(doc.data.presigned_url);
  const content = await response.json();
}

回应: TPostV1DocumentResponse

type TPostV1DocumentResponse = {
  status_code: number;
  status?: string;
  message?: string;
  data?: {
    document_id: string;
    session_id: string;
    template_id: string;
    document_name: string;
    type: string;
    status: string;
    errors: unknown[];
    warnings: unknown[];
    usage_information: Record<string, unknown>;
    document_path: {
      bucket: string;
      folder: string;
      filename: string;
    };
    presigned_url: string;
    created_at: string;
    updated_at: number;
    publish: Record<string, unknown>;
  };
};

patchSessionStatus(request, sessionId?)

更新会话属性(病人细节,状态,模板).

await ekascribe.sessions.patchSessionStatus({
  patient_details: { name: 'Jane Doe', age: '30', gender: 'female' },
  additional_data: { notes: 'Follow-up visit' },
  templates: ['soap', 'prescription'],
}, sessionId);

发现

getDiscoveryDocument()

初始化时获取原始发现文件 。 包含服务器能力(所支持的模型,语言,上传方法,音频格式).

const discovery = ekascribe.sessions.getDiscoveryDocument();

回返 DiscoveryDocument | null。 。 。 .

getDiscoveryConfig()

从发现文档中获取解析的配置 .

const config = ekascribe.sessions.getDiscoveryConfig();

if (config.success) {
  console.log('Resolved config:', config.data);
}

回返 SDKResult<ResolvedConfig>。 。 。 .


部件

SDK提供了可选的预建录音UI. 当启用时, SDK 通过 Shadow DOM 向您的页面注入了浮动部件—— 您写入零 UI 代码 .

一体化

步骤1: 启用 SDK 配置中带有会话默认和回调的部件 :

const ekascribe = getEkaScribeInstance({
  access_token: token,
  env: 'PROD',
  allianceConfig: { baseUrl: '...' },
  widget: {
    enabled: true,
    orientation: 'horizontal',          // 'horizontal' | 'vertical'
    zIndex: 9999,                       // optional
    position: { bottom: 20, right: 20 }, // optional
    sessionDefaults: {
      input_language: ['en'],
      output_format_template: [{ template_id: 'soap' }],
      model_type: 'pro',
      mode: 'consultation',
    },
    callbacks: {
      onRecordingStart: ({ txn_id }) => {},
      onRecordingStop: ({ txn_id, duration }) => {},
      onProcessingComplete: ({ txn_id, sessionData }) => {
        // sessionData contains templates, transcript, etc.
      },
      onError: ({ error_code, message }) => {},
    },
  },
});

步骤2: 打电话 startForPatient() 对于每个病人——部件出现,用户直接与之互动(暂停、恢复、停止)。 你通过回调得到结果.

await ekascribe.startForPatient({
  txn_id: 'unique-session-id',
  patient_details: {                  // optional
    username: 'John Doe',
    age: 45,
    biologicalSex: 'M',
  },
  additional_data: {},                // optional
});

就是这样。 部件处理 startRecordingV2(), (中文(简体) ), pauseRecording(), (中文(简体) ), resumeRecording(), (中文(简体) ), endRecording(),以及 getSessionStatus() 内部.

行为

  • 可拖动 ——部件可以在屏幕上的任何位置重新定位.
  • 一次录一回 电话 startForPatient() 当录制活动返回错误时。 如果部件处于DODE或错误状态,则自动重置并启动新会话.
  • 状态 ——处理后,部件会扩展以显示笔录并制作出平分笔记. 如果两者都可用,则以单独的分页显示.

部件状态流程

COLLAPSED ──> RECORDING ──> PAUSED ──> RECORDING ──> PROCESSING ──> DONE
     ^             │                                       │           │
     │             └──── (user clicks stop) ───────────────┘           │
     │                                                                 │
     └──────────── (user clicks close) ────────────────────────────────┘
                                                   │
                                               ERROR

类型

interface WidgetConfig {
  enabled: boolean;
  theme?: 'light' | 'dark';
  zIndex?: number;
  primaryColor?: string;
  position?: { bottom?: number; right?: number; top?: number; left?: number };
  orientation?: 'horizontal' | 'vertical';
  callbacks?: WidgetCallbacks;
  sessionDefaults: {
    input_language: string[];
    output_format_template: { template_id: string; template_name?: string; template_type?: string }[];
    model_type: string;
    mode: string;
  };
}

interface StartForPatientConfig {
  txn_id: string;
  patient_details?: {
    username?: string;
    age?: number;
    biologicalSex?: string;
    mobile?: string;
  };
  additional_data?: Record<string, unknown>;
}

interface WidgetCallbacks {
  onRecordingStart?: (data: { txn_id: string }) => void;
  onRecordingPause?: (data: { txn_id: string; duration: number }) => void;
  onRecordingResume?: (data: { txn_id: string }) => void;
  onRecordingStop?: (data: { txn_id: string; duration: number }) => void;
  onProcessingStart?: (data: { txn_id: string }) => void;
  onProcessingComplete?: (data: { txn_id: string; sessionData: unknown }) => void;
  onError?: (data: { error_code: string; message: string }) => void;
  onWidgetClose?: (data: { txn_id: string }) => void;
}

认证

updateAuthTokens(token)

手动更新访问符 。 这向所有内部运输者和工人宣传该标志.

ekascribe.updateAuthTokens({ access_token: 'new-token' });

如果你有的话 onTokenRequired sDK自动处理401s。 你们只需要 updateAuthTokens() 用于主动代号旋转(如到期前).


共享工人配置

SDK会卸载音频压缩并上传到一个共享工作人,以便更好的主线程性能. 如果共享工人不可用或失败,SDK静默地回落到主线程处理.

设置

import { createWorkerBlobUrl } from '@eka-care/ekascribe-ts-sdk';

// Option 1: Use the built-in helper (recommended)
const workerUrl = await createWorkerBlobUrl();

// Option 2: Fetch from CDN
async function getWorkerUrl() {
  const res = await fetch(
    'https://cdn.jsdelivr.net/npm/@eka-care/ekascribe-ts-sdk@latest/dist/worker.bundle.js'
  );
  const script = await res.text();
  const blob = new Blob([script], { type: 'application/javascript' });
  return URL.createObjectURL(blob);
}
const workerUrl = await getWorkerUrl();

// Option 3: Copy to public directory
// cp node_modules/@eka-care/ekascribe-ts-sdk/dist/worker.bundle.js public/
const workerUrl = '/worker.bundle.js';

通过配置的 URL :

const ekascribe = getEkaScribeInstance({
  // ...
  sharedWorkerUrl: workerUrl,
});

注释:

  • 工人的URL必须来自同一来源,或有适当的CORS头
  • 完成时记得取消 blob URL : URL.revokeObjectURL(workerUrl)
  • 若为 sharedWorkerUrl 未提供, SDK 使用主线程( 没有共享工人)

错误代码

错误代码说明
microphone麦克风访问出错(拒绝或无法访问)
txn_init_failed初始化会话失败
txn_limit_exceeded最多同时举行的会议超过
internal_server_error服务器侧出错
end_recording_failed结束记录失败
audio_upload_failed音频文件上传到服务器失败
txn_commit_failed提交调用失败
txn_status_mismatch当前会话状态的操作无效
network_error网络连接问题
unknown_error未分类错误
unauthorized认证失败( 无效或过期的令牌)
forbidden权限不足

折旧方法

这些方法取自更古老的SDK版本. 他们仍然在工作,但没有被推荐进行新的融合.

折旧方法替换使用
initTransaction() + 键 startRecording()startRecordingV2()
getTemplateOutput()getSessionStatus() 有民调
getOutputTranscription()getSessionStatus() 有民调
commitTransactionCall()自动处理 endRecording()
stopTransactionCall()自动处理 endRecording()

initTransaction(request)

在服务器上创建会话 。 之后必须 startRecording()。 。 。 .

const result = await ekascribe.initTransaction({
  mode: 'consultation',
  input_language: ['en-IN'],
  output_format_template: [{ template_id: 'template-id' }],
  txn_id: 'unique-id',
  transfer: 'chunked',
  model_type: 'pro',
  patient_details: {                // optional
    username: 'John Doe',
    age: 45,
    biologicalSex: 'M',
  },
});
// result: { status_code, message, txn_id?, error_code? }

startRecording(microphoneID?)

开始录制已初始化的会话 .

const result = await ekascribe.startRecording();
// result: { status_code, message, txn_id?, error_code? }

getTemplateOutput(request)

为会话获取已处理的模板输出 .

const result = await ekascribe.getTemplateOutput({ txn_id: 'session-id' });
// result: { status_code, message?, response? }

getOutputTranscription(request)

获取会话的复制输出 .

const result = await ekascribe.getOutputTranscription({ txn_id: 'session-id' });
// result: { status_code, message?, response? }

commitTransactionCall()

在服务器上提交当前交易 .

const result = await ekascribe.commitTransactionCall();
// result: { status_code, message, error_code?, failed_files? }

stopTransactionCall()

停止服务器上的当前交易.

const result = await ekascribe.stopTransactionCall();
// result: { status_code, message, error_code? }

完整示例

import {
  getEkaScribeInstance,
  type EkaScribeConfig,
  type RecordingOptions,
} from '@eka-care/ekascribe-ts-sdk';

// 1. Initialize
const config: EkaScribeConfig = {
  access_token: token,
  env: 'PROD',
  allianceConfig: {
    baseUrl: 'https://api.eka.care/voice/v1',
  },
};

const ekascribe = getEkaScribeInstance(config);

// 2. Register callbacks
ekascribe.registerCallback('onTokenRequired', async () => {
  return await refreshToken();
});

ekascribe.registerCallback('onUploadEvent', (event) => {
  if (event.type === 'progress') {
    updateProgressUI(event.data.successCount, event.data.totalCount);
  }
});

ekascribe.registerCallback('onError', (event) => {
  showErrorToast(event.error.message);
});

// 3. Start recording
const startResult = await ekascribe.startRecordingV2({
  templates: ['soap'],
  sessionMode: 'consultation',
  languageHint: ['en'],
  patientDetails: { name: 'John Doe', age: '45', gender: 'male' },
});

if (startResult.error_code) {
  showError(startResult.message);
  return;
}

const sessionId = startResult.txn_id!;

// 4. User interacts...
// pauseBtn.onclick = () => ekascribe.pauseRecording();
// resumeBtn.onclick = () => ekascribe.resumeRecording();

// 5. End recording
const endResult = await ekascribe.endRecording();

if (endResult.error_code === 'audio_upload_failed') {
  await ekascribe.retryUploadRecording();
}

// 6. Get results
const status = await ekascribe.getSessionStatus(sessionId, {
  poll: {
    maxAttempts: 60,
    intervalMs: 2000,
    onProgress: (s) => updateStatusUI(s.status),
  },
});

if (status.success) {
  displayResults(status.data.templates, status.data.transcript);
}

// 7. Cleanup on unmount
await ekascribe.resetInstance();

贡献准则

这是一个不断更新的开源项目. 欢迎捐款!

参考 EkaScribe TS SDK 软件 用于SDK执行.

版本与发布记录

@eka-care/ekascribe-ts-sdk 共发布 326 个版本,首次发布于 2025/08/14;过去 12 个月发布了 204 个版本。

版本发布日期距今
3.0.58latest2026/10/2224 天前
3.0.572026/10/081 个月前
3.0.562026/09/072 个月前
3.0.552026/09/072 个月前
3.0.542026/09/072 个月前
3.0.532026/09/072 个月前

其他发布通道:hotfix → 3.0.37-hotfix.0。

关于 @eka-care/ekascribe-ts-sdk 的常见问题

@eka-care/ekascribe-ts-sdk 是什么?

EkaScribe TypeSDK - 现代ES2020建设

如何安装 @eka-care/ekascribe-ts-sdk?

在项目目录运行 npm install @eka-care/ekascribe-ts-sdk,或使用 pnpm add / yarn add / bun add。

@eka-care/ekascribe-ts-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@eka-care/ekascribe-ts-sdk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@eka-care/ekascribe-ts-sdk 可以商用吗?

@eka-care/ekascribe-ts-sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@eka-care/ekascribe-ts-sdk 的下载量有多少?

根据 npm 官方下载统计,@eka-care/ekascribe-ts-sdk 在 2026/10/13 – 2026/11/11 这 30 天内被下载 1,956 次,日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@eka-care/ekascribe-ts-sdk 还在维护吗?

最新版本 3.0.58 发布于 2026/10/22(24 天前);至今共发布 326 个版本,其中过去 12 个月发布了 204 个;首次发布于 2025/08/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。