lomasub 0.1.1 → 0.1.3

package/README.md

@@ -20,7 +20,7 @@ For a Node.js project, run `npm install lomasub`. For a persistent CLI, run `npm
 ```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 --config options.json
 lomasub transcribe video.mp4 --no-ffmpeg
 lomasub download <job-id> --output video.srt
 lomasub --help
@@ -42,7 +42,7 @@ When ffmpeg is on `PATH`, audio is extracted into a temporary Matroska audio fil
 }
 ```
 
-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.
+Supported transcription flags use kebab-case. Use `--promodel pro` (SDK: `config: { promodel: "pro" }`) for word correction before alignment. Revision settings (`revise_srt`, `revise_speakername`, `srt_revision_backend`) are not supported by this CLI/SDK, including through `--config` JSON. 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. Other additional config keys pass through unchanged.
 
 | Settings | CLI flags |
 | --- | --- |
@@ -50,10 +50,11 @@ Every current transcription config field has a kebab-case flag. Boolean fields s
 | 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.
 
+The server defaults omitted, null, or blank language to `th`; `--language en` overrides it. The Thai hint permits Thai, English, and mixed transcripts: readable English is not discarded because of its script. This is a model hint, not automatic language detection.
+
 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
@@ -63,25 +64,38 @@ import { LomaClient } from 'lomasub';
 
 const client = new LomaClient(); // LOMA_API_SECRET_KEY; or { apiKey, endpoint }
 const result = await client.transcribeFile('./video.mp4', {
+  output: './video.srt',
   language: 'th',
   config: { speaker_diarization: true, srt_max_chars: 48 },
   onProgress: event => console.error(event),
 });
-await client.downloadSrt(result.job_id, './video.srt');
+console.log(result.output_path, result.timing);
 ```
 
-Methods return plain API data; result URLs include whichever artifacts the server produced.
+Results include API job data and whichever artifact URLs the server produced. `transcribeFile()` also returns timing and, when saved, `output_path`.
 
 | 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 |
+| `transcribeFile(file, options?)` | Submit, wait, optionally save SRT, and return timing |
 | `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.
 
+`transcribeFile()` additionally accepts `output` (SRT path) and `overwrite` (default `false`). Existing output files are rejected before uploading unless overwrite is enabled.
+
+After successful CLI transcription, stderr includes a final summary:
+
+```text
+Content: 600.00s | Total: 60.00s | Speed: 10.00x realtime
+```
+
+The SDK returns `timing: { content_duration_seconds, total_seconds, speed_x }`. Total time uses a monotonic clock and includes extraction, upload, queueing, processing, and saving the SRT when `output` is provided. Without `output`, timing ends at READY. Speed is content duration divided by total time: 10x means ten seconds of content per second elapsed. SDK numbers retain full precision; CLI values show two decimal places.
+
+Content duration comes from the worker's measured `audio_duration_seconds`, falling back to your explicit `duration_seconds` hint. Missing duration/speed is `null` in the SDK and `unknown` in the CLI; zero duration is valid. Failures and cancellation produce no success summary. Standalone `download` does not report whole-run timing because it cannot measure the earlier local steps.
+
 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.

package/cli.js

@@ -17,6 +17,24 @@ for (const [key, type] of Object.entries(TRANSCRIPTION_OPTIONS)) {
   if (type === 'boolean') options[`no-${flag}`] = { type: 'boolean' };
 }
 
+// Display-only production defaults; omitted options still use the API's settings.
+const DEFAULT_HELP = {
+  forcealigner_level: 'default; choices: default, llmsplitting, none',
+  promodel: 'disabled (omitted/null); use pro to enable word correction',
+  min_vad_duration_seconds: '10',
+  max_vad_duration_seconds: '25',
+  vad_threshold: '0.30',
+  min_srt_duration_ms: '1200',
+  srt_max_chars: '48',
+  srt_cue_words: '6',
+  speaker_diarization: 'disabled',
+  speaker_local_distance_threshold: '0.60',
+  speaker_merge_distance_threshold: '0.35',
+  speaker_clustering_drop_dialogue_percentile: '0.02',
+  agglomeration_min_appear: '5',
+  agglomolation_group_size: '300',
+};
+
 function number(value, flag) {
   const parsed = Number(value);
   if (!value.trim() || !Number.isFinite(parsed)) throw new Error(`--${flag} requires a number.`);
@@ -32,17 +50,20 @@ async function main() {
 
 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
+  --language <code>     ASR language hint: th, en; server default: th
   --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')}`);
+Transcription options:
+Defaults shown are for api.lomasub.ai; omitted options use server settings.
+${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => {
+  const flag = key.replaceAll('_', '-');
+  const label = `--${flag}${type === 'boolean' ? ` / --no-${flag}` : ` <${type}>`}`;
+  return `  ${label.padEnd(56)}default: ${DEFAULT_HELP[key]}`;
+}).join('\n')}`);
     return;
   }
   const [command, input] = positionals;
@@ -77,8 +98,14 @@ ${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => `  --${key.replaceA
   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));
+    if (command === 'download') console.log(await client.downloadSrt(input, output, settings));
+    else {
+      const result = await client.transcribeFile(input, { ...settings, output });
+      const { content_duration_seconds, total_seconds, speed_x } = result.timing;
+      const format = (value, unit) => value === null ? 'unknown' : `${value.toFixed(2)}${unit}`;
+      console.error(`Content: ${format(content_duration_seconds, 's')} | Total: ${format(total_seconds, 's')} | Speed: ${format(speed_x, 'x realtime')}`);
+      console.log(result.output_path);
+    }
   } finally {
     process.removeListener('SIGINT', cancel);
     process.removeListener('SIGTERM', cancel);

package/index.d.ts

@@ -1,4 +1,5 @@
 export interface TranscriptionConfig {
+  promodel?: 'pro' | null;
   forcealigner_level?: 'default' | 'llmsplitting' | 'none';
   min_vad_duration_seconds?: number;
   max_vad_duration_seconds?: number;
@@ -12,9 +13,6 @@ export interface TranscriptionConfig {
   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;
 }
 
@@ -32,6 +30,8 @@ export interface WaitOptions {
 }
 
 export interface TranscribeOptions extends WaitOptions {
+  output?: string;
+  overwrite?: boolean;
   ffmpeg?: boolean;
   config?: TranscriptionConfig;
   filename?: string;
@@ -47,6 +47,7 @@ export interface Job {
 }
 
 export interface JobStatus extends Job {
+  audio_duration_seconds?: number | null;
   config?: TranscriptionConfig;
   failed_stage?: string | null;
   error?: string | null;
@@ -58,6 +59,15 @@ export interface JobStatus extends Job {
   debug_vtt_url?: string;
 }
 
+export interface TranscriptionResult extends JobStatus {
+  output_path?: string;
+  timing: {
+    content_duration_seconds: number | null;
+    total_seconds: number;
+    speed_x: number | null;
+  };
+}
+
 export const TRANSCRIPTION_OPTIONS: Readonly<Record<string, 'string' | 'number' | 'boolean'>>;
 
 export class LomaClient {
@@ -65,6 +75,6 @@ export class LomaClient {
   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>;
+  transcribeFile(file: string, options?: TranscribeOptions): Promise<TranscriptionResult>;
   downloadSrt(jobId: string, output: string, options?: WaitOptions & { overwrite?: boolean }): Promise<string>;
 }

package/index.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { createReadStream, createWriteStream } from 'node:fs';
-import { link, mkdtemp, rename, rm, stat } from 'node:fs/promises';
+import { link, lstat, 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';
@@ -13,6 +13,7 @@ const run = promisify(execFile);
 // Shared with the CLI; validation and transcription defaults belong to the API.
 export const TRANSCRIPTION_OPTIONS = {
   forcealigner_level: 'string',
+  promodel: 'string',
   min_vad_duration_seconds: 'number',
   max_vad_duration_seconds: 'number',
   vad_threshold: 'number',
@@ -25,9 +26,6 @@ export const TRANSCRIPTION_OPTIONS = {
   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 = {
@@ -69,6 +67,9 @@ export class LomaClient {
   async submitFile(file, options = {}) {
     const { signal, onProgress = () => {}, ffmpeg = true, config, language, duration_seconds } = options;
     signal?.throwIfAborted();
+    for (const key of ['revise_srt', 'revise_speakername', 'srt_revision_backend']) {
+      if (config && Object.hasOwn(config, key)) throw new Error(`config.${key} is not supported by the CLI/SDK.`);
+    }
     const original = resolve(file);
     if (!(await stat(original)).isFile()) throw new Error(`Not a regular file: ${file}`);
     let source = original;
@@ -88,10 +89,12 @@ export class LomaClient {
         }
       }
       signal?.throwIfAborted();
+      const size_bytes = (await stat(source)).size;
       const upload = await this.request('/presigned-url', {
         filename: basename(source),
         content_type: MIME_TYPES[extname(source).toLowerCase()] ?? 'application/octet-stream',
         duration_seconds,
+        size_bytes,
       }, signal);
       if (upload.method !== 'PUT' || !upload.upload_url || !upload.source_url || !upload.headers) {
         throw new Error('Invalid /presigned-url response.');
@@ -100,7 +103,7 @@ export class LomaClient {
       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) },
+          method: upload.method, headers: { ...upload.headers, 'Content-Length': String(size_bytes) },
           body: stream, duplex: 'half', signal,
         }, 'Upload');
         await response.arrayBuffer();
@@ -134,13 +137,32 @@ export class LomaClient {
   }
 
   async transcribeFile(file, options = {}) {
+    const started = performance.now();
+    if (options.output !== undefined && !options.overwrite) {
+      try {
+        await lstat(options.output);
+        throw new Error(`Output exists: ${options.output}. Set overwrite: true to replace it.`);
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
     const job = await this.submitFile(file, options);
-    return this.waitForJob(job.job_id, options);
+    const status = await this.waitForJob(job.job_id, options);
+    const output_path = options.output === undefined ? undefined : await this.#saveSrt(status, options.output, options);
+    const total_seconds = (performance.now() - started) / 1000;
+    const content_duration_seconds = [status.audio_duration_seconds, options.duration_seconds]
+      .find(value => Number.isFinite(value) && value >= 0) ?? null;
+    const speed = content_duration_seconds === null ? null : content_duration_seconds / total_seconds;
+    return { ...status, ...(output_path === undefined ? {} : { output_path }), timing: {
+      content_duration_seconds, total_seconds, speed_x: Number.isFinite(speed) ? speed : null,
+    } };
   }
 
   async downloadSrt(jobId, output, options = {}) {
-    const { signal, overwrite = false, onProgress = () => {} } = options;
     const status = await this.waitForJob(jobId, options);
+    return this.#saveSrt(status, output, options);
+  }
+
+  async #saveSrt(status, output, { signal, overwrite = false, onProgress = () => {} }) {
+    const jobId = status.job_id;
     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-'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lomasub",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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" },