voxflow 1.15.0 → 1.15.2

package/lib/core/asr-client.js

@@ -0,0 +1,448 @@
+/**
+ * VoxFlow CLI — ASR (Automatic Speech Recognition) API client
+ *
+ * Wraps the three backend ASR endpoints:
+ *   - POST /api/asr/sentence   (≤60 s, sync, base64 or URL)
+ *   - POST /api/asr/flash      (≤2 h,  sync, URL only)
+ *   - POST /api/asr/file       (≤5 h,  async → poll for result)
+ *
+ * Provides automatic mode selection based on audio duration.
+ */
+
+const fs = require('fs');
+const { request, throwApiError, throwNetworkError, ApiError } = require('./http');
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** Upper duration limit for sentence recognition (ms) */
+const SENTENCE_MAX_MS = 60_000;
+
+/** Upper duration limit for flash recognition (ms) */
+const FLASH_MAX_MS = 7_200_000;
+
+/** Maximum file size for base64 upload (bytes). Above this, use COS URL. */
+const BASE64_MAX_BYTES = 5 * 1024 * 1024;
+
+/** Default polling interval for async file tasks (ms) */
+const POLL_INTERVAL_MS = 3_000;
+
+/** Maximum polling duration before giving up (ms) — 5 minutes */
+const POLL_TIMEOUT_MS = 300_000;
+
+// Task status codes returned by DescribeTaskStatus
+const TASK_STATUS = {
+  WAITING: 0,
+  PROCESSING: 1,
+  SUCCESS: 2,
+  FAILED: 3,
+};
+
+// ─── Mode detection ─────────────────────────────────────────────────────────
+
+/**
+ * Choose the best ASR mode based on audio duration and input type.
+ *
+ * @param {number}  durationMs  - Audio duration in milliseconds
+ * @param {boolean} hasUrl      - Whether a URL is available (COS or remote)
+ * @param {number}  fileSize    - File size in bytes
+ * @returns {'sentence'|'flash'|'file'}
+ */
+function detectMode(durationMs, hasUrl, fileSize) {
+  if (durationMs <= SENTENCE_MAX_MS && fileSize <= BASE64_MAX_BYTES) {
+    return 'sentence';
+  }
+  if (durationMs <= FLASH_MAX_MS && hasUrl) {
+    return 'flash';
+  }
+  return 'file';
+}
+
+// ─── Request helpers ────────────────────────────────────────────────────────
+
+function authHeaders(token) {
+  return {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${token}`,
+  };
+}
+
+// ─── Sentence recognition ───────────────────────────────────────────────────
+
+/**
+ * Recognize audio ≤ 60 s using SentenceRecognition (sync).
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase
+ * @param {string} opts.token
+ * @param {string} [opts.url]         - COS / remote URL
+ * @param {string} [opts.filePath]    - Local file (will be base64-encoded)
+ * @param {string} [opts.lang]        - Engine model, e.g. '16k_zh' (default)
+ * @param {boolean}[opts.wordInfo]    - Return word-level timestamps
+ * @returns {Promise<{result: string, audioTime: number, wordList?: Array, requestId: string, quota: object}>}
+ */
+async function recognizeSentence(opts) {
+  const { apiBase, token, url, filePath, lang = '16k_zh', wordInfo = false } = opts;
+
+  const body = {
+    EngSerViceType: lang,       // Note: backend uses this exact (mis)spelling
+    VoiceFormat: 'wav',
+    SubServiceType: 2,
+    WordInfo: wordInfo ? 1 : 0,
+    ConvertNumMode: 1,
+  };
+
+  if (url) {
+    body.Url = url;
+    body.SourceType = 0;
+  } else if (filePath) {
+    const buf = fs.readFileSync(filePath);
+    body.Data = buf.toString('base64');
+    body.DataLen = buf.length;
+    body.SourceType = 1;
+  } else {
+    throw new Error('Either url or filePath is required for sentence recognition');
+  }
+
+  try {
+    const { status, data } = await request(
+      `${apiBase}/api/asr/sentence`,
+      { method: 'POST', headers: authHeaders(token) },
+      body
+    );
+
+    if (status !== 200 || data.code !== 'success') {
+      throwApiError(status, data, 'ASR sentence');
+    }
+
+    return {
+      result: data.result,
+      audioTime: data.audioTime,
+      wordList: data.wordList || [],
+      requestId: data.requestId,
+      quota: data.quota,
+    };
+  } catch (err) {
+    if (err instanceof ApiError) throw err;
+    throwNetworkError(err, apiBase);
+  }
+}
+
+// ─── Flash recognition ──────────────────────────────────────────────────────
+
+/**
+ * Recognize audio ≤ 2 h using Flash API (sync, URL only).
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase
+ * @param {string} opts.token
+ * @param {string} opts.url            - Audio URL (required)
+ * @param {string} [opts.lang]         - Engine type, e.g. '16k_zh'
+ * @param {boolean}[opts.speakerDiarization] - Enable speaker separation
+ * @param {number} [opts.speakerNumber]      - Expected speaker count
+ * @returns {Promise<{flashResult: Array, audioDuration: number, requestId: string, quota: object}>}
+ */
+async function recognizeFlash(opts) {
+  const {
+    apiBase, token, url, lang = '16k_zh',
+    speakerDiarization = false, speakerNumber = 0,
+  } = opts;
+
+  if (!url) {
+    throw new Error('Flash recognition requires a URL (cannot use base64 data)');
+  }
+
+  const body = {
+    engine_type: lang,
+    voice_format: 'wav',
+    url,
+    speaker_diarization: speakerDiarization ? 1 : 0,
+    speaker_number: speakerNumber,
+    filter_dirty: 0,
+    filter_modal: 0,
+    filter_punc: 0,
+    convert_num_mode: 1,
+    word_info: 1,
+    first_channel_only: 1,
+  };
+
+  try {
+    const { status, data } = await request(
+      `${apiBase}/api/asr/flash`,
+      { method: 'POST', headers: authHeaders(token) },
+      body
+    );
+
+    if (status !== 200 || data.code !== 'success') {
+      throwApiError(status, data, 'ASR flash');
+    }
+
+    return {
+      flashResult: data.flash_result || [],
+      audioDuration: data.audio_duration || 0,
+      requestId: data.request_id,
+      quota: data.quota,
+    };
+  } catch (err) {
+    if (err instanceof ApiError) throw err;
+    throwNetworkError(err, apiBase);
+  }
+}
+
+// ─── File recognition (async) ───────────────────────────────────────────────
+
+/**
+ * Submit a long audio file for async recognition (CreateRecTask).
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase
+ * @param {string} opts.token
+ * @param {string} [opts.url]
+ * @param {string} [opts.filePath]       - Local file (base64, ≤5 MB only)
+ * @param {string} [opts.lang]           - e.g. '16k_zh'
+ * @param {boolean}[opts.speakerDiarization]
+ * @param {number} [opts.speakerNumber]
+ * @returns {Promise<{taskId: number, requestId: string, quota: object}>}
+ */
+async function submitFileTask(opts) {
+  const {
+    apiBase, token, url, filePath, lang = '16k_zh',
+    speakerDiarization = false, speakerNumber = 0,
+  } = opts;
+
+  const body = {
+    EngineModelType: lang,
+    ChannelNum: 1,
+    ResTextFormat: 0,
+    FilterDirty: 0,
+    FilterModal: 0,
+    FilterPunc: 0,
+    ConvertNumMode: 1,
+    SpeakerDiarization: speakerDiarization ? 1 : 0,
+    SpeakerNumber: speakerNumber,
+  };
+
+  if (url) {
+    body.Url = url;
+    body.SourceType = 0;
+  } else if (filePath) {
+    const buf = fs.readFileSync(filePath);
+    if (buf.length > BASE64_MAX_BYTES) {
+      throw new Error(
+        `File too large for base64 upload (${(buf.length / 1024 / 1024).toFixed(1)} MB). ` +
+        'Upload to COS first or use flash mode with a URL.'
+      );
+    }
+    body.Data = buf.toString('base64');
+    body.DataLen = buf.length;
+    body.SourceType = 1;
+  } else {
+    throw new Error('Either url or filePath is required for file recognition');
+  }
+
+  try {
+    const { status, data } = await request(
+      `${apiBase}/api/asr/file`,
+      { method: 'POST', headers: authHeaders(token) },
+      body
+    );
+
+    if (status !== 200 || data.code !== 'success') {
+      throwApiError(status, data, 'ASR file submit');
+    }
+
+    return {
+      taskId: data.taskId,
+      requestId: data.requestId,
+      quota: data.quota,
+    };
+  } catch (err) {
+    if (err instanceof ApiError) throw err;
+    throwNetworkError(err, apiBase);
+  }
+}
+
+/**
+ * Poll a file recognition task until it completes or fails.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.apiBase
+ * @param {string}   opts.token
+ * @param {number}   opts.taskId
+ * @param {number}   [opts.pollIntervalMs]  - ms between polls (default 3000)
+ * @param {number}   [opts.pollTimeoutMs]   - max wait (default 300000)
+ * @param {function} [opts.onProgress]      - callback(status, elapsed) for UI updates
+ * @returns {Promise<{result: string, audioTime: number, status: number}>}
+ */
+async function pollTaskResult(opts) {
+  const {
+    apiBase, token, taskId,
+    pollIntervalMs = POLL_INTERVAL_MS,
+    pollTimeoutMs = POLL_TIMEOUT_MS,
+    onProgress,
+  } = opts;
+
+  const started = Date.now();
+
+  // eslint-disable-next-line no-constant-condition -- task-poll loop, exits via throw/return
+  while (true) {
+    const elapsed = Date.now() - started;
+    if (elapsed > pollTimeoutMs) {
+      throw new Error(
+        `ASR task ${taskId} timed out after ${Math.round(elapsed / 1000)}s. ` +
+        'The task may still complete — check later with: voxflow asr --task-id ' + taskId
+      );
+    }
+
+    try {
+      const { status, data } = await request(
+        `${apiBase}/api/asr/result/${taskId}`,
+        { method: 'GET', headers: authHeaders(token) }
+      );
+
+      if (status !== 200 || data.code !== 'success') {
+        throwApiError(status, data, 'ASR poll');
+      }
+
+      const taskData = data.data;
+      const taskStatus = taskData.Status;
+
+      if (onProgress) onProgress(taskStatus, elapsed);
+
+      if (taskStatus === TASK_STATUS.SUCCESS) {
+        return {
+          result: taskData.Result,
+          audioTime: taskData.AudioTime,
+          status: taskStatus,
+        };
+      }
+
+      if (taskStatus === TASK_STATUS.FAILED) {
+        throw new Error(
+          `ASR task ${taskId} failed: ${taskData.Result || 'Unknown error'}`
+        );
+      }
+
+      // Still waiting or processing — sleep then retry
+    } catch (err) {
+      if (err instanceof ApiError) throw err;
+      // Transient network errors during polling — log and retry
+      if (elapsed + pollIntervalMs < pollTimeoutMs) {
+        // swallow and retry
+      } else {
+        throwNetworkError(err, apiBase);
+      }
+    }
+
+    await sleep(pollIntervalMs);
+  }
+}
+
+// ─── Unified recognize function ─────────────────────────────────────────────
+
+/**
+ * High-level: recognize audio using the best available mode.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.apiBase
+ * @param {string}  opts.token
+ * @param {string}  opts.mode            - 'auto', 'sentence', 'flash', 'file'
+ * @param {string}  [opts.url]           - Remote or COS URL
+ * @param {string}  [opts.filePath]      - Local WAV file path
+ * @param {number}  opts.durationMs      - Audio duration in ms
+ * @param {number}  [opts.fileSize]      - File size in bytes
+ * @param {string}  [opts.lang]          - Engine model (default '16k_zh')
+ * @param {boolean} [opts.speakerDiarization]
+ * @param {number}  [opts.speakerNumber]
+ * @param {boolean} [opts.wordInfo]
+ * @param {function}[opts.onProgress]    - Polling progress callback
+ * @returns {Promise<{mode: string, result: string, flashResult?: Array, audioTime: number, wordList?: Array, quota: object}>}
+ */
+async function recognize(opts) {
+  const {
+    mode: requestedMode = 'auto',
+    url, durationMs, fileSize = 0,
+  } = opts;
+
+  // Determine actual mode
+  const hasUrl = !!url;
+  const actualMode = requestedMode === 'auto'
+    ? detectMode(durationMs, hasUrl, fileSize)
+    : requestedMode;
+
+  switch (actualMode) {
+    case 'sentence': {
+      const res = await recognizeSentence(opts);
+      return {
+        mode: 'sentence',
+        result: res.result,
+        audioTime: res.audioTime,
+        wordList: res.wordList,
+        quota: res.quota,
+      };
+    }
+
+    case 'flash': {
+      if (!url) {
+        throw new Error(
+          'Flash mode requires a URL. Upload the file to COS first, or use --mode auto.'
+        );
+      }
+      const res = await recognizeFlash(opts);
+      // Flatten flash segments into a single result text
+      const fullText = (res.flashResult || [])
+        .flatMap((seg) =>
+          seg.sentence_list
+            ? seg.sentence_list.map((s) => s.text)
+            : [seg.text]
+        )
+        .join('');
+      return {
+        mode: 'flash',
+        result: fullText,
+        flashResult: res.flashResult,
+        audioDuration: res.audioDuration,
+        audioTime: (res.audioDuration || 0) / 1000,
+        quota: res.quota,
+      };
+    }
+
+    case 'file': {
+      const submitRes = await submitFileTask(opts);
+      const pollRes = await pollTaskResult({
+        apiBase: opts.apiBase,
+        token: opts.token,
+        taskId: submitRes.taskId,
+        onProgress: opts.onProgress,
+      });
+      return {
+        mode: 'file',
+        result: pollRes.result,
+        audioTime: pollRes.audioTime,
+        taskId: submitRes.taskId,
+        quota: submitRes.quota,
+      };
+    }
+
+    default:
+      throw new Error(`Unknown ASR mode: ${actualMode}. Use: auto, sentence, flash, or file`);
+  }
+}
+
+// ─── Utility ────────────────────────────────────────────────────────────────
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  recognize,
+  recognizeSentence,
+  recognizeFlash,
+  submitFileTask,
+  pollTaskResult,
+  detectMode,
+  SENTENCE_MAX_MS,
+  FLASH_MAX_MS,
+  BASE64_MAX_BYTES,
+  TASK_STATUS,
+};

package/lib/core/asr-jobs-client.js

@@ -0,0 +1,126 @@
+/**
+ * VoxFlow CLI — HTTP client for /api/asr/jobs/*.
+ *
+ * Thin wrappers over `request()` — they unwrap the standard
+ * `{ code: 'success', data: { ... } }` envelope and surface non-2xx as
+ * ApiError so callers can match on `err.code`/`err.status`.
+ *
+ * The backend lazy-polls Azure on every GET /api/asr/jobs/:id, so the CLI
+ * just calls getJob in a backoff loop without needing a separate "sync" RPC.
+ */
+
+const { request, throwApiError, throwNetworkError } = require('./http');
+
+function authHeaders(token) {
+  return {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${token}`
+  };
+}
+
+async function call(apiBase, method, path, token, body) {
+  let res;
+  try {
+    res = await request(`${apiBase}${path}`, {
+      method,
+      headers: authHeaders(token)
+    }, body);
+  } catch (err) {
+    throwNetworkError(err, apiBase);
+  }
+  if (res.status < 200 || res.status >= 300) {
+    throwApiError(res.status, res.data, `ASR jobs ${method} ${path}`);
+  }
+  return res.data?.data || res.data;
+}
+
+/**
+ * Create a new ASR job. Charges quota and submits to Azure server-side.
+ *
+ * @param {object} args
+ * @param {string} args.apiBase
+ * @param {string} args.token
+ * @param {string} args.sourceKey      R2 key returned by uploadToR2()
+ * @param {string} [args.sourceFilename]
+ * @param {number} [args.sourceSize]
+ * @param {number} args.durationSec    used to compute quota cost server-side
+ * @param {string} [args.language='auto']
+ * @param {object} [args.options]      { wordTimestamps?, diarize?, speakerCount?, candidateLocales? }
+ */
+async function createJob({
+  apiBase, token, sourceKey, sourceFilename, sourceSize,
+  durationSec, language = 'auto', options = {}
+}) {
+  const data = await call(apiBase, 'POST', '/api/asr/jobs', token, {
+    sourceKey,
+    sourceFilename,
+    sourceSize,
+    durationSec,
+    language,
+    options
+  });
+  return data.job;
+}
+
+async function getJob(apiBase, token, jobId) {
+  const data = await call(apiBase, 'GET', `/api/asr/jobs/${encodeURIComponent(jobId)}`, token);
+  return data.job;
+}
+
+async function listJobs(apiBase, token, { limit = 20, before } = {}) {
+  const params = new URLSearchParams();
+  if (limit) params.set('limit', String(limit));
+  if (before) params.set('before', before);
+  const qs = params.toString();
+  const data = await call(apiBase, 'GET', `/api/asr/jobs${qs ? `?${qs}` : ''}`, token);
+  return data.jobs || [];
+}
+
+async function cancelJob(apiBase, token, jobId) {
+  const data = await call(apiBase, 'DELETE', `/api/asr/jobs/${encodeURIComponent(jobId)}`, token);
+  return data.job;
+}
+
+const TERMINAL_STATUSES = new Set(['succeeded', 'failed', 'cancelled']);
+
+/**
+ * Poll the backend until the job hits a terminal state (or `signal` aborts).
+ *
+ * Backoff schedule keeps the prompt cache warm for short jobs and slows down
+ * for long ones: 2s → 5s → 10s → 30s capped.
+ *
+ * @param {object}   args
+ * @param {string}   args.apiBase
+ * @param {string}   args.token
+ * @param {string}   args.jobId
+ * @param {function} [args.onProgress]  (job) => void   called every poll
+ * @param {AbortSignal} [args.signal]
+ * @returns {Promise<object>} terminal job row
+ */
+async function waitForTerminal({ apiBase, token, jobId, onProgress, signal }) {
+  const intervals = [2000, 5000, 10000, 30000];
+  let i = 0;
+  while (true) {
+    if (signal?.aborted) {
+      const e = new Error('Aborted');
+      e.code = 'aborted';
+      throw e;
+    }
+    const job = await getJob(apiBase, token, jobId);
+    if (onProgress) onProgress(job);
+    if (TERMINAL_STATUSES.has(job.status)) return job;
+    const delay = intervals[Math.min(i, intervals.length - 1)];
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    i++;
+  }
+}
+
+module.exports = {
+  createJob,
+  getJob,
+  listJobs,
+  cancelJob,
+  waitForTerminal,
+  TERMINAL_STATUSES,
+  __internals: { call }
+};

package/lib/core/asr-jobs-store.js

@@ -0,0 +1,105 @@
+/**
+ * VoxFlow CLI — Local persistence for in-flight ASR jobs.
+ *
+ * Why: ASR jobs run minutes-to-hours server-side. If the user closes the
+ * terminal or hits Ctrl+C, the server-side job keeps going (Azure doesn't
+ * care that we walked away). This store keeps a tiny pointer file per job
+ * so the next `voxflow asr` invocation can find and resume them.
+ *
+ * Layout:
+ *   ~/.config/voxflow/jobs/asr-<jobId>.json
+ *
+ * Schema (kept minimal — backend is the source of truth):
+ *   {
+ *     jobId, createdAt, status, source: { path, filename, durationSec },
+ *     language, options, lastPolledAt
+ *   }
+ *
+ * The file is rewritten on every poll so a stale `status` field always
+ * matches the last network observation. Cancel/cleanup deletes the file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config');
+
+function getJobsDir() {
+  const dir = path.join(getConfigDir(), 'jobs');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function jobFilePath(jobId) {
+  // jobId is a UUID from the backend — safe to interpolate, but defend
+  // against future format changes by stripping anything path-unsafe.
+  const safe = String(jobId).replace(/[^A-Za-z0-9._-]/g, '_');
+  return path.join(getJobsDir(), `asr-${safe}.json`);
+}
+
+function saveJob(jobId, record) {
+  const file = jobFilePath(jobId);
+  const payload = JSON.stringify({
+    jobId,
+    ...record,
+    lastPolledAt: new Date().toISOString()
+  }, null, 2);
+  // atomic write: tmp + rename so a Ctrl+C mid-write doesn't corrupt.
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, payload);
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+function loadJob(jobId) {
+  const file = jobFilePath(jobId);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function listJobs() {
+  const dir = getJobsDir();
+  const files = fs.readdirSync(dir).filter((f) => f.startsWith('asr-') && f.endsWith('.json'));
+  return files
+    .map((f) => {
+      try { return JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); }
+      catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
+}
+
+function deleteJob(jobId) {
+  const file = jobFilePath(jobId);
+  try { fs.unlinkSync(file); return true; } catch { return false; }
+}
+
+// Prune jobs that have been in a terminal state for more than `maxAgeDays`.
+// Called opportunistically by the asr command so the dir doesn't grow forever.
+function pruneTerminal(maxAgeDays = 30) {
+  const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+  let removed = 0;
+  for (const job of listJobs()) {
+    if (!['succeeded', 'failed', 'cancelled'].includes(job.status)) continue;
+    const ts = Date.parse(job.lastPolledAt || job.createdAt || 0);
+    if (Number.isFinite(ts) && ts < cutoff) {
+      deleteJob(job.jobId);
+      removed++;
+    }
+  }
+  return removed;
+}
+
+module.exports = {
+  saveJob,
+  loadJob,
+  listJobs,
+  deleteJob,
+  pruneTerminal,
+  getJobsDir,
+  // Test helpers
+  __internals: { jobFilePath }
+};