lomasub 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# Loma Sub: Node.js SDK and CLI
+
+Create subtitles from a local audio or video file. Requires Node.js 20+ and a Loma Sub API key. No runtime npm dependencies.
+
+## Install
+
+From this repository (the package has not been published to npm):
+
+```bash
+npm install --global ./cli-sdk
+export LOMA_API_SECRET_KEY="<your-api-key>"
+lomasub transcribe ./video.mp4 --language th
+```
+
+For a Node.js project, run `npm install /path/to/loma_fastsrt/cli-sdk` instead.
+
+## CLI
+
+```bash
+lomasub transcribe video.mp4 --output video.srt
+lomasub transcribe video.mp4 --speaker-diarization --srt-max-chars 48 --srt-cue-words 6
+lomasub transcribe video.mp4 --config options.json --no-revise-srt
+lomasub transcribe video.mp4 --no-ffmpeg
+lomasub download <job-id> --output video.srt
+lomasub --help
+```
+
+The command uploads the file, creates the job, waits, and saves `<input-stem>.srt` beside the input. `--output` changes the destination; `--overwrite` permits replacing an existing file. Progress and the job ID go to stderr; the saved path goes to stdout. If interrupted, the server job continues: resume using `download` and the printed job ID. Errors exit with code 1; cancellation exits with code 130. Job creation is never automatically retried.
+
+When ffmpeg is on `PATH`, audio is extracted into a temporary Matroska audio file using `-map 0:a:0 -vn -c:a copy`. This copies the first audio stream without encoding, resampling, or changing quality. It excludes video to reduce uploads. If ffmpeg is missing or extraction fails (including a codec unsupported by Matroska), the original file is uploaded. `--no-ffmpeg` disables extraction. Temporary files are removed afterward.
+
+`--config` reads an object of API transcription settings, without a surrounding `config` key:
+
+```json
+{
+  "forcealigner_level": "default",
+  "speaker_diarization": true,
+  "srt_max_chars": 48,
+  "srt_cue_words": 6,
+  "min_srt_duration_ms": 1200
+}
+```
+
+Every current transcription config field has a kebab-case flag. Boolean fields support `--name` and `--no-name`. Explicit flags override JSON values, including `false` and `0`. Unset settings use server defaults; the API validates settings and reports retired names. Additional config keys pass through unchanged.
+
+| Settings | CLI flags |
+| --- | --- |
+| Alignment | `--forcealigner-level` (`default`, `llmsplitting`, `none`) |
+| VAD | `--min-vad-duration-seconds`, `--max-vad-duration-seconds`, `--vad-threshold` |
+| Subtitle cues | `--min-srt-duration-ms`, `--srt-max-chars`, `--srt-cue-words` |
+| Diarization | `--speaker-diarization`, `--speaker-local-distance-threshold`, `--speaker-merge-distance-threshold`, `--speaker-clustering-drop-dialogue-percentile`, `--agglomeration-min-appear`, `--agglomolation-group-size` |
+| Revision | `--revise-srt`, `--revise-speakername`, `--srt-revision-backend` (`agy`, `codex`) |
+
+`--filename`, `--language`, and `--duration-seconds` are job metadata, outside config. The original local filename is preserved unless overridden. An explicit duration is forwarded to upload preparation and job creation; duration is not automatically measured.
+
+Use `--endpoint http://localhost:8080` for another API server. The default is `https://api.lomasub.ai`. Bearer credentials are sent only to the API, never to storage upload/download URLs.
+
+## SDK
+
+```js
+import { LomaClient } from 'lomasub';
+
+const client = new LomaClient(); // LOMA_API_SECRET_KEY; or { apiKey, endpoint }
+const result = await client.transcribeFile('./video.mp4', {
+  language: 'th',
+  config: { speaker_diarization: true, srt_max_chars: 48 },
+  onProgress: event => console.error(event),
+});
+await client.downloadSrt(result.job_id, './video.srt');
+```
+
+Methods return plain API data; result URLs include whichever artifacts the server produced.
+
+| Method | Behavior |
+| --- | --- |
+| `submitFile(file, options?)` | Extract/upload and return the newly created job |
+| `getStatus(jobId, { signal }?)` | Read current status and fresh download URLs |
+| `waitForJob(jobId, options?)` | Poll until READY; throw with the failed stage on FAILED |
+| `transcribeFile(file, options?)` | Submit and wait |
+| `downloadSrt(jobId, output, options?)` | Wait if needed, download original SRT, return absolute saved path |
+
+Transcription options: `config`, `filename`, `language`, `duration_seconds`, `ffmpeg` (default `true`), `signal`, `onProgress`, and `pollIntervalMs` (default `2000`). Waiting/downloading accept `signal`, `onProgress`, and `pollIntervalMs`; downloading also accepts `overwrite` (default `false`). Output parent directories must already exist.
+
+Pass an `AbortController`'s `signal` to stop local work. A submitted job continues on the server. HTTP errors include `status` and `detail`; ordinary network/file errors propagate. There are no automatic retries.
+
+This package covers transcription and original results only. Account/login, job-history management, subtitle editing, and edited-subtitle uploads are outside its scope.
+
+## Development
+
+```bash
+cd cli-sdk
+npm test
+npm run check
+npm pack --dry-run
+```
+
+Tests use local mock HTTP servers. One optional ffmpeg test checks that stream-copy extraction preserves audio packet bytes. No production jobs are submitted.

package/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { lstat, readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { LomaClient, TRANSCRIPTION_OPTIONS } from './index.js';
+
+const options = {
+  help: { type: 'boolean', short: 'h' },
+  endpoint: { type: 'string' }, output: { type: 'string', short: 'o' },
+  config: { type: 'string' }, language: { type: 'string' }, filename: { type: 'string' },
+  'duration-seconds': { type: 'string' },
+  'no-ffmpeg': { type: 'boolean' }, overwrite: { type: 'boolean' },
+};
+for (const [key, type] of Object.entries(TRANSCRIPTION_OPTIONS)) {
+  const flag = key.replaceAll('_', '-');
+  options[flag] = { type: type === 'boolean' ? 'boolean' : 'string' };
+  if (type === 'boolean') options[`no-${flag}`] = { type: 'boolean' };
+}
+
+function number(value, flag) {
+  const parsed = Number(value);
+  if (!value.trim() || !Number.isFinite(parsed)) throw new Error(`--${flag} requires a number.`);
+  return parsed;
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({ options, allowPositionals: true });
+  if (values.help || !positionals.length) {
+    console.log(`Usage:
+  lomasub transcribe <file> [options]
+  lomasub download <job-id> --output <file.srt> [--overwrite]
+
+Set LOMA_API_SECRET_KEY before running. Default endpoint: https://api.lomasub.ai
+Options:
+  --endpoint <url>       API endpoint
+  --output, -o <path>    Output SRT (default: beside input)
+  --overwrite           Replace existing output
+  --no-ffmpeg           Upload original without audio extraction
+  --language <code>     Audio language
+  --filename <name>     Job display filename
+  --duration-seconds N  Optional media duration hint
+  --config <path>       JSON transcription config; explicit flags override it
+
+Transcription options (unset values use server defaults):
+${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => `  --${key.replaceAll('_', '-')}${type === 'boolean' ? ' / --no-' + key.replaceAll('_', '-') : ' <' + type + '>'}`).join('\n')}`);
+    return;
+  }
+  const [command, input] = positionals;
+  if (!['transcribe', 'download'].includes(command) || !input || positionals.length !== 2) {
+    throw new Error('Use transcribe <file> or download <job-id>. See --help.');
+  }
+  if (command === 'download' && !values.output) throw new Error('download requires --output.');
+  const output = resolve(values.output ?? `${input.slice(0, input.length - extname(input).length)}.srt`);
+  if (!values.overwrite) {
+    try {
+      await lstat(output);
+      throw new Error(`Output exists: ${output}. Use --overwrite to replace it.`);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  const config = values.config ? JSON.parse(await readFile(values.config, 'utf8')) : {};
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('--config must contain a JSON object.');
+  for (const [key, type] of Object.entries(TRANSCRIPTION_OPTIONS)) {
+    const flag = key.replaceAll('_', '-');
+    if (values[flag] !== undefined && values[`no-${flag}`] !== undefined) throw new Error(`Conflicting --${flag} and --no-${flag}.`);
+    if (values[`no-${flag}`]) config[key] = false;
+    else if (values[flag] !== undefined) config[key] = type === 'number' ? number(values[flag], flag) : values[flag];
+  }
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  const settings = {
+    signal: controller.signal, overwrite: values.overwrite, ffmpeg: !values['no-ffmpeg'],
+    language: values.language, filename: values.filename, config,
+    duration_seconds: values['duration-seconds'] === undefined ? undefined : number(values['duration-seconds'], 'duration-seconds'),
+    onProgress: ({ stage, job_id, state, message }) => console.error([stage, job_id, state, message].filter(Boolean).join(': ')),
+  };
+  process.once('SIGINT', cancel);
+  process.once('SIGTERM', cancel);
+  try {
+    const client = new LomaClient({ endpoint: values.endpoint });
+    const jobId = command === 'download' ? input : (await client.submitFile(input, settings)).job_id;
+    console.log(await client.downloadSrt(jobId, output, settings));
+  } finally {
+    process.removeListener('SIGINT', cancel);
+    process.removeListener('SIGTERM', cancel);
+  }
+}
+
+main().catch(error => {
+  console.error(error.name === 'AbortError' ? 'Cancelled. An already-submitted job continues; resume with lomasub download <job-id> --output <path>.' : error.message);
+  process.exitCode = error.name === 'AbortError' ? 130 : 1;
+});

package/index.d.ts

@@ -0,0 +1,70 @@
+export interface TranscriptionConfig {
+  forcealigner_level?: 'default' | 'llmsplitting' | 'none';
+  min_vad_duration_seconds?: number;
+  max_vad_duration_seconds?: number;
+  vad_threshold?: number;
+  min_srt_duration_ms?: number;
+  srt_max_chars?: number;
+  srt_cue_words?: number;
+  speaker_diarization?: boolean;
+  speaker_local_distance_threshold?: number;
+  speaker_merge_distance_threshold?: number;
+  speaker_clustering_drop_dialogue_percentile?: number;
+  agglomeration_min_appear?: number;
+  agglomolation_group_size?: number;
+  revise_srt?: boolean;
+  revise_speakername?: boolean;
+  srt_revision_backend?: 'agy' | 'codex';
+  [key: string]: unknown;
+}
+
+export interface Progress {
+  stage: 'extracting' | 'fallback' | 'uploading' | 'submitted' | 'processing' | 'downloading';
+  job_id?: string;
+  state?: string;
+  message?: string;
+}
+
+export interface WaitOptions {
+  signal?: AbortSignal;
+  onProgress?: (progress: Progress) => void;
+  pollIntervalMs?: number;
+}
+
+export interface TranscribeOptions extends WaitOptions {
+  ffmpeg?: boolean;
+  config?: TranscriptionConfig;
+  filename?: string;
+  language?: string;
+  duration_seconds?: number;
+}
+
+export interface Job {
+  job_id: string;
+  state: string;
+  status_url?: string;
+  [key: string]: unknown;
+}
+
+export interface JobStatus extends Job {
+  config?: TranscriptionConfig;
+  failed_stage?: string | null;
+  error?: string | null;
+  srt_url?: string;
+  vtt_url?: string;
+  compact_url?: string;
+  karaoke_vtt_url?: string;
+  words_url?: string;
+  debug_vtt_url?: string;
+}
+
+export const TRANSCRIPTION_OPTIONS: Readonly<Record<string, 'string' | 'number' | 'boolean'>>;
+
+export class LomaClient {
+  constructor(options?: { apiKey?: string; endpoint?: string });
+  submitFile(file: string, options?: TranscribeOptions): Promise<Job>;
+  getStatus(jobId: string, options?: Pick<WaitOptions, 'signal'>): Promise<JobStatus>;
+  waitForJob(jobId: string, options?: WaitOptions): Promise<JobStatus>;
+  transcribeFile(file: string, options?: TranscribeOptions): Promise<JobStatus>;
+  downloadSrt(jobId: string, output: string, options?: WaitOptions & { overwrite?: boolean }): Promise<string>;
+}

package/index.js

@@ -0,0 +1,159 @@
+import { execFile } from 'node:child_process';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { link, mkdtemp, rename, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+// Shared with the CLI; validation and transcription defaults belong to the API.
+export const TRANSCRIPTION_OPTIONS = {
+  forcealigner_level: 'string',
+  min_vad_duration_seconds: 'number',
+  max_vad_duration_seconds: 'number',
+  vad_threshold: 'number',
+  min_srt_duration_ms: 'number',
+  srt_max_chars: 'number',
+  srt_cue_words: 'number',
+  speaker_diarization: 'boolean',
+  speaker_local_distance_threshold: 'number',
+  speaker_merge_distance_threshold: 'number',
+  speaker_clustering_drop_dialogue_percentile: 'number',
+  agglomeration_min_appear: 'number',
+  agglomolation_group_size: 'number',
+  revise_srt: 'boolean',
+  revise_speakername: 'boolean',
+  srt_revision_backend: 'string',
+};
+
+const MIME_TYPES = {
+  '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.mp4': 'video/mp4',
+  '.wav': 'audio/wav', '.flac': 'audio/flac', '.ogg': 'audio/ogg',
+  '.opus': 'audio/ogg', '.aac': 'audio/aac', '.webm': 'video/webm',
+  '.mov': 'video/quicktime', '.mkv': 'video/x-matroska', '.mka': 'audio/x-matroska',
+};
+
+async function checkedFetch(url, options, stage) {
+  const response = await fetch(url, { ...options, redirect: 'error' });
+  if (!response.ok) {
+    const text = await response.text();
+    let detail = text;
+    try { detail = JSON.parse(text).detail ?? text; } catch { /* Non-JSON storage errors. */ }
+    throw Object.assign(new Error(`${stage}: HTTP ${response.status}: ${typeof detail === 'string' ? detail : JSON.stringify(detail)}`), {
+      status: response.status, detail,
+    });
+  }
+  return response;
+}
+
+export class LomaClient {
+  constructor({ apiKey = process.env.LOMA_API_SECRET_KEY, endpoint = 'https://api.lomasub.ai' } = {}) {
+    if (!apiKey) throw new Error('Set LOMA_API_SECRET_KEY or provide apiKey.');
+    this.apiKey = apiKey;
+    this.endpoint = endpoint.replace(/\/+$/, '');
+  }
+
+  async request(path, body, signal) {
+    const response = await checkedFetch(`${this.endpoint}${path}`, {
+      method: body === undefined ? 'GET' : 'POST', signal,
+      headers: { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    }, path);
+    return response.json();
+  }
+
+  async submitFile(file, options = {}) {
+    const { signal, onProgress = () => {}, ffmpeg = true, config, language, duration_seconds } = options;
+    signal?.throwIfAborted();
+    const original = resolve(file);
+    if (!(await stat(original)).isFile()) throw new Error(`Not a regular file: ${file}`);
+    let source = original;
+    let temporary;
+    try {
+      if (ffmpeg) {
+        temporary = await mkdtemp(join(tmpdir(), 'lomasub-audio-'));
+        const audio = join(temporary, 'audio.mka');
+        onProgress({ stage: 'extracting' });
+        try {
+          await run('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-nostdin', '-i', original,
+            '-map', '0:a:0', '-vn', '-c:a', 'copy', audio], { signal });
+          source = audio;
+        } catch (error) {
+          signal?.throwIfAborted();
+          onProgress({ stage: 'fallback', message: `Audio extraction unavailable or failed; uploading original. ${error.message}` });
+        }
+      }
+      signal?.throwIfAborted();
+      const upload = await this.request('/presigned-url', {
+        filename: basename(source),
+        content_type: MIME_TYPES[extname(source).toLowerCase()] ?? 'application/octet-stream',
+        duration_seconds,
+      }, signal);
+      if (upload.method !== 'PUT' || !upload.upload_url || !upload.source_url || !upload.headers) {
+        throw new Error('Invalid /presigned-url response.');
+      }
+      onProgress({ stage: 'uploading' });
+      const stream = createReadStream(source);
+      try {
+        const response = await checkedFetch(upload.upload_url, {
+          method: upload.method, headers: { ...upload.headers, 'Content-Length': String((await stat(source)).size) },
+          body: stream, duplex: 'half', signal,
+        }, 'Upload');
+        await response.arrayBuffer();
+      } finally { stream.destroy(); }
+      const job = await this.request('/new-transcribe', {
+        source_url: upload.source_url, filename: options.filename ?? basename(original),
+        language, duration_seconds, config,
+      }, signal);
+      onProgress({ stage: 'submitted', job_id: job.job_id });
+      return job;
+    } finally {
+      if (temporary) await rm(temporary, { recursive: true, force: true });
+    }
+  }
+
+  getStatus(jobId, { signal } = {}) {
+    return this.request(`/status?${new URLSearchParams({ job_id: jobId })}`, undefined, signal);
+  }
+
+  async waitForJob(jobId, { signal, onProgress = () => {}, pollIntervalMs = 2000 } = {}) {
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) throw new Error('pollIntervalMs must be positive.');
+    let previous;
+    while (true) {
+      const status = await this.getStatus(jobId, { signal });
+      if (status.state !== previous) onProgress({ stage: 'processing', job_id: jobId, state: status.state });
+      previous = status.state;
+      if (status.state === 'READY') return status;
+      if (status.state === 'FAILED') throw new Error(`Job ${jobId} failed at ${status.failed_stage ?? 'unknown stage'}: ${status.error ?? 'Unknown error'}`);
+      await sleep(pollIntervalMs, undefined, { signal });
+    }
+  }
+
+  async transcribeFile(file, options = {}) {
+    const job = await this.submitFile(file, options);
+    return this.waitForJob(job.job_id, options);
+  }
+
+  async downloadSrt(jobId, output, options = {}) {
+    const { signal, overwrite = false, onProgress = () => {} } = options;
+    const status = await this.waitForJob(jobId, options);
+    if (!status.srt_url) throw new Error(`Job ${jobId} has no SRT URL.`);
+    const target = resolve(output);
+    const temporary = await mkdtemp(join(dirname(target), '.lomasub-download-'));
+    const partial = join(temporary, 'result.srt');
+    try {
+      onProgress({ stage: 'downloading', job_id: jobId });
+      const response = await checkedFetch(status.srt_url, { signal }, 'Download');
+      await pipeline(Readable.fromWeb(response.body), createWriteStream(partial), { signal });
+      signal?.throwIfAborted();
+      // link fails atomically if the destination exists; rename replaces it only when requested.
+      if (overwrite) await rename(partial, target);
+      else await link(partial, target);
+      return target;
+    } finally { await rm(temporary, { recursive: true, force: true }); }
+  }
+}

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "lomasub",
+  "version": "0.1.0",
+  "description": "Lomasub cli is a command-line tool for creating subtitles from local audio or video in Node.js or the terminal, using lomasub.ai cloud service. ",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "exports": { ".": { "types": "./index.d.ts", "default": "./index.js" } },
+  "types": "./index.d.ts",
+  "bin": { "lomasub": "./cli.js" },
+  "files": ["index.js", "index.d.ts", "cli.js", "README.md"],
+  "scripts": { "test": "node --test", "check": "node --check index.js && node --check cli.js" }
+}