lomasub 0.1.2 → 0.2.0

package/README.md

@@ -20,13 +20,19 @@ 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 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.
 
@@ -42,7 +48,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 +56,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
@@ -80,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:
 
@@ -109,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('_', '-');
@@ -17,6 +18,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; 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',
+  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.`);
@@ -29,29 +48,43 @@ 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:
-  --endpoint <url>       API endpoint
-  --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>     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;
   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.`);
@@ -65,26 +98,46 @@ ${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => `  --${key.replaceA
     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);
@@ -92,6 +145,8 @@ ${Object.entries(TRANSCRIPTION_OPTIONS).map(([key, type]) => `  --${key.replaceA
 }
 
 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,4 +1,5 @@
 export interface TranscriptionConfig {
+  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;
@@ -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;
 }
 
@@ -31,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;
@@ -70,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 {
@@ -79,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

@@ -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 = {
@@ -50,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.');
@@ -69,6 +74,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 +96,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 +110,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();
@@ -135,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);
@@ -143,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;
@@ -155,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.2",
+  "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" },