lomasub 0.1.0 → 0.1.2

package/README.md

@@ -2,17 +2,18 @@
 
 Create subtitles from a local audio or video file. Requires Node.js 20+ and a Loma Sub API key. No runtime npm dependencies.
 
+Sign in to the editor, open your account dialog, and generate your personal API key. Copy it when shown: it is displayed only once. Each account has one active key; replacing or revoking it immediately invalidates the old key. Your CLI/SDK requests use your account's quota and create jobs in your own history. Inactive accounts cannot use personal keys. The shared deployment secret is reserved for internal scripts and workers.
+
 ## Install
 
-From this repository (the package has not been published to npm):
+Run directly with npx:
 
 ```bash
-npm install --global ./cli-sdk
 export LOMA_API_SECRET_KEY="<your-api-key>"
-lomasub transcribe ./video.mp4 --language th
+npx lomasub transcribe ./video.mp4 --language th
 ```
 
-For a Node.js project, run `npm install /path/to/loma_fastsrt/cli-sdk` instead.
+For a Node.js project, run `npm install lomasub`. For a persistent CLI, run `npm install --global lomasub`. From a repository checkout, `npm install --global ./cli-sdk` also works.
 
 ## CLI
 
@@ -62,25 +63,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

@@ -77,8 +77,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

@@ -32,6 +32,8 @@ export interface WaitOptions {
 }
 
 export interface TranscribeOptions extends WaitOptions {
+  output?: string;
+  overwrite?: boolean;
   ffmpeg?: boolean;
   config?: TranscriptionConfig;
   filename?: string;
@@ -47,6 +49,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 +61,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 +77,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';
@@ -134,13 +134,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.0",
+  "version": "0.1.2",
   "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" },