lomasub 0.1.3 → 0.2.0

package/README.md

@@ -23,10 +23,16 @@ lomasub transcribe video.mp4 --speaker-diarization --srt-max-chars 48 --srt-cue-
 lomasub transcribe video.mp4 --config options.json
 lomasub transcribe video.mp4 --no-ffmpeg
 lomasub download <job-id> --output video.srt
+lomasub transcribe video.mp4 --format txt          # prints only the text, one line
+lomasub transcribe video.mp4 --format txt -v       # same, plus progress on stderr
+lomasub transcribe video.mp4 --format txt -o video.txt
+lomasub download <job-id> --format txt --speakers
 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.
+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. `--output -` prints the result itself to stdout instead of saving it.
+
+`--format txt` returns the transcript as plain text: every cue joined by a single space on one line, with no line breaks at all (not even at the end), no numbers, timings or markup. It is made for scripts: by default it prints **only** the text to stdout, with no progress lines and no file. `--output <file>` saves it instead (silently), `--verbose` / `-v` shows the progress, timing and saved path as SRT does, and `download <job-id> --format txt` needs no `--output`. Errors are always reported on stderr with exit code 1, naming the job ID so it can be fetched later with `download`. It follows the editor: once a subtitle is edited and saved, the text reflects the edit. Speaker labels (`A: ...`, from `--speaker-diarization`) are dropped unless `--speakers` is given. The default format is `srt`. 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.
 
@@ -81,10 +87,14 @@ Results include API job data and whichever artifact URLs the server produced. `t
 | `waitForJob(jobId, options?)` | Poll until READY; throw with the failed stage on FAILED |
 | `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 |
+| `downloadText(jobId, output, options?)` | Wait if needed, save the plain-text transcript, return absolute saved path |
+| `getText(jobId, { signal, speakers }?)` | The plain-text transcript of a READY job as a string |
+| `readResult(jobId, options?)` | Wait if needed and return the result as a string (`format`: `srt` or `txt`) |
+| `resultText(status, options?)` | The result of a READY status (such as `transcribeFile`'s) as a string, without polling again |
 
 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.
+`transcribeFile()` additionally accepts `output` (result path), `format` (`srt` default, or `txt`), `speakers` (txt only, default `false`) and `overwrite` (default `false`). Existing output files are rejected before uploading unless overwrite is enabled.
 
 After successful CLI transcription, stderr includes a final summary:
 
@@ -110,3 +120,15 @@ 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.
+
+
+### Translation
+
+Use one output mode, for example `--promodel translate-zh` for **Simplified Chinese**.
+Other targets: `translate-th` (Thai), `translate-en` (English), `translate-ja`
+(Japanese), `translate-ko` (Korean). `translate-jp` and `translate-kr` are aliases.
+SDK: `config: { promodel: "translate-zh" }`. `language` still names the source
+language. Translation combines conservative correction and translation in one
+batched stage; it never runs `pro` first. Omit the option for original subtitles.
+Use alignment `default` or `none`; `llmsplitting` is incompatible with translation.
+Translated results have fixed cue timing, plain SRT/VTT, and no word-level karaoke.

package/cli.js

@@ -2,7 +2,7 @@
 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';
+import { LomaClient, RESULT_FORMATS, TRANSCRIPTION_OPTIONS } from './index.js';
 
 const options = {
   help: { type: 'boolean', short: 'h' },
@@ -10,6 +10,7 @@ const options = {
   config: { type: 'string' }, language: { type: 'string' }, filename: { type: 'string' },
   'duration-seconds': { type: 'string' },
   'no-ffmpeg': { type: 'boolean' }, overwrite: { type: 'boolean' },
+  format: { type: 'string' }, speakers: { type: 'boolean' }, verbose: { type: 'boolean', short: 'v' },
 };
 for (const [key, type] of Object.entries(TRANSCRIPTION_OPTIONS)) {
   const flag = key.replaceAll('_', '-');
@@ -20,7 +21,7 @@ for (const [key, type] of Object.entries(TRANSCRIPTION_OPTIONS)) {
 // 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',
+  promodel: 'disabled; pro or translate-th/en/ja/ko/zh (zh = Simplified Chinese; jp/kr aliases)',
   min_vad_duration_seconds: '10',
   max_vad_duration_seconds: '25',
   vad_threshold: '0.30',
@@ -47,10 +48,15 @@ async function main() {
     console.log(`Usage:
   lomasub transcribe <file> [options]
   lomasub download <job-id> --output <file.srt> [--overwrite]
+  lomasub download <job-id> --format txt [--output <file.txt>]
 
 Set LOMA_API_SECRET_KEY before running. Default endpoint: https://api.lomasub.ai
 Options:
-  --output, -o <path>    Output SRT (default: beside input)
+  --output, -o <path>    Output file (srt default: beside input); - prints to stdout
+  --format <srt|txt>     srt (default) or txt: all cues on one line, joined by spaces.
+                         txt prints only the text to stdout unless --output is given
+  --speakers            txt only: keep speaker labels (A: ...)
+  --verbose, -v         txt only: show progress and timing on stderr (srt always does)
   --overwrite           Replace existing output
   --no-ffmpeg           Upload original without audio extraction
   --language <code>     ASR language hint: th, en; server default: th
@@ -70,9 +76,15 @@ ${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => {
   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) {
+  const format = values.format ?? 'srt';
+  if (!RESULT_FORMATS.includes(format)) throw new Error(`--format must be one of: ${RESULT_FORMATS.join(', ')}.`);
+  if (values.speakers && format !== 'txt') throw new Error('--speakers requires --format txt.');
+  if (command === 'download' && !values.output && format !== 'txt') throw new Error('download requires --output.');
+  // txt is made for pipes: the text alone on stdout, nothing else unless --verbose.
+  const stdout = values.output === '-' || (format === 'txt' && values.output === undefined);
+  const verbose = format === 'srt' || values.verbose;
+  const output = stdout ? undefined : resolve(values.output ?? `${input.slice(0, input.length - extname(input).length)}.${format}`);
+  if (!stdout && !values.overwrite) {
     try {
       await lstat(output);
       throw new Error(`Output exists: ${output}. Use --overwrite to replace it.`);
@@ -86,26 +98,46 @@ ${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => {
     if (values[`no-${flag}`]) config[key] = false;
     else if (values[flag] !== undefined) config[key] = type === 'number' ? number(values[flag], flag) : values[flag];
   }
+  let jobId = command === 'download' ? input : undefined;
   const controller = new AbortController();
   const cancel = () => controller.abort();
   const settings = {
     signal: controller.signal, overwrite: values.overwrite, ffmpeg: !values['no-ffmpeg'],
+    format, speakers: values.speakers,
     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(': ')),
+    onProgress: ({ stage, job_id, state, message }) => {
+      if (job_id) jobId = job_id;
+      if (verbose) 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 });
-    if (command === 'download') console.log(await client.downloadSrt(input, output, settings));
-    else {
+    // stdout carries exactly the result (txt has no trailing newline); progress stays on stderr.
+    const print = text => new Promise((done, fail) => process.stdout.write(text, error => error ? fail(error) : done()));
+    if (command === 'download') {
+      if (stdout) await print(await client.readResult(input, settings));
+      else {
+        const saved = format === 'txt' ? await client.downloadText(input, output, settings) : await client.downloadSrt(input, output, settings);
+        if (verbose) console.log(saved);
+      }
+    } else {
       const result = await client.transcribeFile(input, { ...settings, output });
+      const text = stdout ? await client.resultText(result, settings) : undefined;
       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);
+      const show = (value, unit) => value === null ? 'unknown' : `${value.toFixed(2)}${unit}`;
+      // Before the text: a txt result ends without a newline, so nothing may follow it.
+      if (verbose) console.error(`Content: ${show(content_duration_seconds, 's')} | Total: ${show(total_seconds, 's')} | Speed: ${show(speed_x, 'x realtime')}`);
+      if (stdout) await print(text);
+      else if (verbose) console.log(result.output_path);
     }
+  } catch (error) {
+    // Quiet mode never printed the job id, so a cancel or failure names it for `download`.
+    error.jobId = jobId;
+    if (jobId && !verbose && error.name !== 'AbortError' && !error.message.includes(jobId)) error.message = `${error.message} (job ${jobId})`;
+    throw error;
   } finally {
     process.removeListener('SIGINT', cancel);
     process.removeListener('SIGTERM', cancel);
@@ -113,6 +145,8 @@ ${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => {
 }
 
 main().catch(error => {
-  console.error(error.name === 'AbortError' ? 'Cancelled. An already-submitted job continues; resume with lomasub download <job-id> --output <path>.' : error.message);
+  console.error(error.name === 'AbortError'
+    ? `Cancelled. An already-submitted job continues; resume with lomasub download ${error.jobId ?? '<job-id>'} --output <path>.`
+    : error.message);
   process.exitCode = error.name === 'AbortError' ? 130 : 1;
 });

package/index.d.ts

@@ -1,5 +1,5 @@
 export interface TranscriptionConfig {
-  promodel?: 'pro' | null;
+  promodel?: 'pro' | 'translate-th' | 'translate-en' | 'translate-ja' | 'translate-ko' | 'translate-zh' | 'translate-jp' | 'translate-kr' | null;
   forcealigner_level?: 'default' | 'llmsplitting' | 'none';
   min_vad_duration_seconds?: number;
   max_vad_duration_seconds?: number;
@@ -29,7 +29,16 @@ export interface WaitOptions {
   pollIntervalMs?: number;
 }
 
-export interface TranscribeOptions extends WaitOptions {
+export type ResultFormat = 'srt' | 'txt';
+
+export interface ResultOptions {
+  /** `srt` (default) or `txt`: every cue joined by one space, on a single line with no newline. */
+  format?: ResultFormat;
+  /** `txt` only: keep the diarization labels (`A: ...`). Default false. */
+  speakers?: boolean;
+}
+
+export interface TranscribeOptions extends WaitOptions, ResultOptions {
   output?: string;
   overwrite?: boolean;
   ffmpeg?: boolean;
@@ -68,6 +77,7 @@ export interface TranscriptionResult extends JobStatus {
   };
 }
 
+export const RESULT_FORMATS: readonly ResultFormat[];
 export const TRANSCRIPTION_OPTIONS: Readonly<Record<string, 'string' | 'number' | 'boolean'>>;
 
 export class LomaClient {
@@ -77,4 +87,8 @@ export class LomaClient {
   waitForJob(jobId: string, options?: WaitOptions): Promise<JobStatus>;
   transcribeFile(file: string, options?: TranscribeOptions): Promise<TranscriptionResult>;
   downloadSrt(jobId: string, output: string, options?: WaitOptions & { overwrite?: boolean }): Promise<string>;
+  downloadText(jobId: string, output: string, options?: WaitOptions & { overwrite?: boolean; speakers?: boolean }): Promise<string>;
+  getText(jobId: string, options?: { signal?: AbortSignal; speakers?: boolean }): Promise<string>;
+  readResult(jobId: string, options?: WaitOptions & ResultOptions): Promise<string>;
+  resultText(status: JobStatus, options?: ResultOptions & Pick<WaitOptions, 'signal' | 'onProgress'>): Promise<string>;
 }

package/index.js

@@ -48,6 +48,13 @@ async function checkedFetch(url, options, stage) {
   return response;
 }
 
+export const RESULT_FORMATS = ['srt', 'txt'];
+
+function resultFormat(format = 'srt') {
+  if (!RESULT_FORMATS.includes(format)) throw new Error(`format must be one of: ${RESULT_FORMATS.join(', ')}.`);
+  return format;
+}
+
 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.');
@@ -138,6 +145,7 @@ export class LomaClient {
 
   async transcribeFile(file, options = {}) {
     const started = performance.now();
+    resultFormat(options.format);
     if (options.output !== undefined && !options.overwrite) {
       try {
         await lstat(options.output);
@@ -146,7 +154,7 @@ export class LomaClient {
     }
     const job = await this.submitFile(file, 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 output_path = options.output === undefined ? undefined : await this.#save(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;
@@ -158,18 +166,62 @@ export class LomaClient {
 
   async downloadSrt(jobId, output, options = {}) {
     const status = await this.waitForJob(jobId, options);
-    return this.#saveSrt(status, output, options);
+    return this.#save(status, output, { ...options, format: 'srt' });
+  }
+
+  async downloadText(jobId, output, options = {}) {
+    const status = await this.waitForJob(jobId, options);
+    return this.#save(status, output, { ...options, format: 'txt' });
+  }
+
+  // The current transcript of a READY job as one line: cues joined by a space, no newline.
+  async getText(jobId, { signal, speakers = false } = {}) {
+    return (await this.#fetchResult({ job_id: jobId }, 'txt', { signal, speakers })).text();
+  }
+
+  // Wait for the job, then return its result as a string (`format`: 'srt' or 'txt').
+  async readResult(jobId, options = {}) {
+    resultFormat(options.format);
+    return this.resultText(await this.waitForJob(jobId, options), options);
+  }
+
+  // The result of an already READY status (e.g. what transcribeFile returned) as a string.
+  async resultText(status, { format, speakers, signal, onProgress = () => {} } = {}) {
+    format = resultFormat(format);
+    onProgress({ stage: 'downloading', job_id: status.job_id });
+    return (await this.#fetchResult(status, format, { signal, speakers })).text();
+  }
+
+  async #fetchResult(status, format, { signal, speakers = false }) {
+    const jobId = status.job_id;
+    if (format === 'srt') {
+      if (!status.srt_url) throw new Error(`Job ${jobId} has no SRT URL.`);
+      return checkedFetch(status.srt_url, { signal }, 'Download');
+    }
+    // Text is derived by the API (it follows editor saves), so it needs the bearer key.
+    const query = speakers ? '?speakers=true' : '';
+    try {
+      return await checkedFetch(`${this.endpoint}/jobs/${encodeURIComponent(jobId)}.txt${query}`, {
+        signal, headers: { Authorization: `Bearer ${this.apiKey}` },
+      }, 'Download');
+    } catch (error) {
+      if (error.status === 404) {
+        error.message = `Job ${jobId} has no text transcript: it is not READY, not yours, or the server does not support .txt yet.`;
+      }
+      throw error;
+    }
   }
 
-  async #saveSrt(status, output, { signal, overwrite = false, onProgress = () => {} }) {
+  async #save(status, output, { signal, overwrite = false, onProgress = () => {}, format, speakers }) {
+    format = resultFormat(format);
     const jobId = status.job_id;
-    if (!status.srt_url) throw new Error(`Job ${jobId} has no SRT URL.`);
+    if (format === 'srt' && !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');
+    const partial = join(temporary, `result.${format}`);
     try {
       onProgress({ stage: 'downloading', job_id: jobId });
-      const response = await checkedFetch(status.srt_url, { signal }, 'Download');
+      const response = await this.#fetchResult(status, format, { signal, speakers });
       await pipeline(Readable.fromWeb(response.body), createWriteStream(partial), { signal });
       signal?.throwIfAborted();
       // link fails atomically if the destination exists; rename replaces it only when requested.

package/package.json

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