@transcribe-api/sdk 0.1.3 → 0.1.5

package/worker.js

@@ -3,12 +3,13 @@ const MAX_BATCH_FILES = 10000;
 const MAX_BATCH_TOTAL_SIZE_BYTES = 10 * 1024 * 1024 * 1024;
 const MAX_SYNC_AUDIO_BYTES = 30 * 1024 * 1024;
 const MAX_SYNC_AUDIO_SECONDS = 10 * 60;
-const MULTIPART_UPLOAD_THRESHOLD_BYTES = 100 * 1024 * 1024;
-const DEFAULT_MULTIPART_CONCURRENCY = 8;
-const MAX_MULTIPART_CONCURRENCY = 32;
+const MULTIPART_UPLOAD_THRESHOLD_BYTES = 128 * 1024 * 1024;
+const DEFAULT_UPLOAD_CONCURRENCY = 1;
+const MAX_UPLOAD_CONCURRENCY = 32;
 const MAX_MULTIPART_ADAPTIVE_ATTEMPTS = 12;
 const MULTIPART_IDLE_WAIT_MS = 50;
 const MIN_POLLING_INTERVAL_SECONDS = 10;
+const DEFAULT_POLLING_SPINNER_INTERVAL_MS = 150;
 const TERMINAL_JOB_STATUSES = new Set(["completed", "failed", "insufficient_funds"]);
 const BATCH_MP4_UNSUPPORTED_MESSAGE = "Batch uploads do not support .mp4 for MVP. Supported batch audio formats: mp3, mpeg, mpga, m4a, wav, webm.";
 const BATCH_UNSUPPORTED_MESSAGE = "Unsupported batch audio format. Supported batch audio formats: mp3, mpeg, mpga, m4a, wav, webm.";
@@ -82,7 +83,8 @@ async function retry(operation, { attempts = 3, baseDelayMs = 250 } = {}) {
       return await operation(index);
     } catch (error) {
       lastError = error;
-      if (!isRetryableError(error) || index === attempts - 1) {
+      const retryable = isRetryableError(error);
+      if (!retryable || index === attempts - 1) {
         throw error;
       }
       await sleep(baseDelayMs * (2 ** index));
@@ -91,17 +93,17 @@ async function retry(operation, { attempts = 3, baseDelayMs = 250 } = {}) {
   throw lastError;
 }
 
-function normalizeMultipartConcurrency(value) {
+function normalizeUploadConcurrency(value) {
   if (value === undefined || value === null || value === "") {
-    return DEFAULT_MULTIPART_CONCURRENCY;
+    return DEFAULT_UPLOAD_CONCURRENCY;
   }
   const parsed = Number.parseInt(String(value), 10);
   if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new TranscribeAPIError("`multipartConcurrency` must be an integer >= 1.", {
-      code: "invalid_multipart_concurrency",
+    throw new TranscribeAPIError("`uploadConcurrency` must be an integer >= 1.", {
+      code: "invalid_upload_concurrency",
     });
   }
-  return Math.min(parsed, MAX_MULTIPART_CONCURRENCY);
+  return Math.min(parsed, MAX_UPLOAD_CONCURRENCY);
 }
 
 function normalizePollingConfig(polling) {
@@ -152,31 +154,39 @@ function contentTypeFromName(name = "") {
   return "application/octet-stream";
 }
 
-function isRemoteFileInput(input) {
+function isRemoteBatchItem(input) {
   return Boolean(input && typeof input === "object" && typeof input.url === "string");
 }
 
-function isRemoteBatchItem(input) {
-  return Boolean(input && typeof input === "object" && typeof input.url === "string");
+function isFilesInput(input) {
+  return Array.isArray(input);
+}
+
+function normalizeLanguageCode(language, fieldName = "`language`") {
+  const value = String(language || "").trim().toLowerCase();
+  if (!value || value === "auto") {
+    return null;
+  }
+  if (!/^[a-z]{2}$/i.test(value)) {
+    throw new TranscribeAPIError(`${fieldName} must be a two-letter language code such as \`en\` or \`fr\`.`, {
+      code: "invalid_language",
+    });
+  }
+  return value;
 }
 
 function defaultReferenceId(index) {
-  return `file_${String(index + 1).padStart(6, "0")}`;
+  return String(index + 1).padStart(5, "0");
 }
 
 function normalizeBatchInputItem(item, index) {
   if (!item || typeof item !== "object" || Array.isArray(item)) {
-    throw new TranscribeAPIError("Each batch item must be an object with `reference_id` and either `file` or `url`.", {
+    throw new TranscribeAPIError("Each batch item must be an object with either `file` or `url`.", {
       code: "invalid_batch_item",
     });
   }
 
-  const referenceId = String(item.reference_id || "").trim();
-  if (!referenceId) {
-    throw new TranscribeAPIError(`files[${index}].reference_id is required.`, {
-      code: "missing_reference_id",
-    });
-  }
+  const referenceId = String(item.reference_id || "").trim() || null;
 
   const hasFile = Object.prototype.hasOwnProperty.call(item, "file");
   const hasUrl = typeof item.url === "string" && item.url.trim();
@@ -196,11 +206,14 @@ function normalizeBatchInputItem(item, index) {
     file: hasFile ? item.file : null,
     url: hasUrl ? item.url.trim() : null,
     durationEstimateSec: item.durationEstimateSec || item.duration_estimate_sec || null,
+    hasLanguage: Object.prototype.hasOwnProperty.call(item, "language"),
+    language: normalizeLanguageCode(item.language, `files[${index}].language`),
   };
 }
 
 function uploadDescriptorForFile(referenceId, file) {
-  const descriptor = { reference_id: referenceId };
+  const descriptor = {};
+  if (referenceId) descriptor.reference_id = referenceId;
   if (Number(file?.size || 0) >= MULTIPART_UPLOAD_THRESHOLD_BYTES) {
     descriptor.size_bytes = Number(file.size || 0);
   }
@@ -230,9 +243,10 @@ function uploadFromResponse(response, referenceId) {
 }
 
 function emitProgress(handler, event) {
-  if (typeof handler === "function") {
-    handler(event);
+  if (typeof handler !== "function") {
+    return;
   }
+  handler(event);
 }
 
 function renderProgressBar(loaded, total, width = 30) {
@@ -253,60 +267,151 @@ function formatBytes(bytes) {
 }
 
 function createSdkLoggerProgressHandler(logger = console) {
+  let activeProgressLine = false;
+  let lastRenderedLength = 0;
+
+  const writeLine = (line) => {
+    if (activeProgressLine && typeof process !== "undefined" && process?.stdout?.write) {
+      process.stdout.write("\r".padEnd(lastRenderedLength + 1, " "));
+      process.stdout.write("\n");
+      activeProgressLine = false;
+      lastRenderedLength = 0;
+    }
+    if (typeof logger?.log === "function") {
+      logger.log(line);
+    }
+  };
+
+  const writeProgress = (line) => {
+    if (typeof process !== "undefined" && process?.stdout?.write) {
+      const paddedLine = line.padEnd(lastRenderedLength, " ");
+      lastRenderedLength = paddedLine.length;
+      process.stdout.write(`\r${paddedLine}`);
+      activeProgressLine = true;
+      return;
+    }
+    if (typeof logger?.log === "function") {
+      logger.log(line);
+    }
+  };
+
   return (event) => {
-    if (!event || typeof event !== "object" || typeof logger?.log !== "function") {
+    if (!event || typeof event !== "object") {
       return;
     }
     if (event.event === "upload_started") {
-      logger.log(`Uploading ${event.uploadFiles}/${event.totalFiles} local file(s) for ${event.jobId}, ${formatBytes(event.totalBytes)} total`);
+      writeLine(`Uploading ${event.uploadFiles} file(s) for ${event.jobId}`);
       return;
     }
     if (event.event === "upload_progress") {
       const loaded = Number(event.batchLoaded ?? event.loaded ?? 0);
       const total = Number(event.batchTotal ?? event.total ?? 0);
       const percent = total ? ((loaded / total) * 100).toFixed(1) : "0.0";
-      logger.log(`Uploading ${renderProgressBar(loaded, total)} ${percent}% (${formatBytes(loaded)} / ${formatBytes(total)})`);
+      writeProgress(`Uploading ${renderProgressBar(loaded, total)} ${percent}% (${formatBytes(loaded)} / ${formatBytes(total)})`);
+      if (total && loaded >= total && activeProgressLine && typeof process !== "undefined" && process?.stdout?.write) {
+        process.stdout.write("\n");
+        activeProgressLine = false;
+        lastRenderedLength = 0;
+      }
       return;
     }
-    if (event.event === "upload_completed" && !event.suppressLog) {
-      logger.log(`Uploaded completed: ${JSON.stringify(event.response, null, 2)}`);
+    if (event.event === "upload_completed") {
+      if (event.suppressLog) {
+        if (activeProgressLine && typeof process !== "undefined" && process?.stdout?.write) {
+          process.stdout.write("\n");
+          activeProgressLine = false;
+          lastRenderedLength = 0;
+        }
+        return;
+      }
+      writeLine(`Uploaded completed: ${JSON.stringify(event.response, null, 2)}`);
     }
   };
 }
 
 function createSdkPollingLogger(logger = console) {
-  let lastStatus = null;
+  let spinnerTimer = null;
+  let activeLine = false;
+  let currentFrameIndex = 0;
+  let currentStatus = "waiting";
+  let currentJobId = "unknown_job";
+  let lastRenderedLength = 0;
+  const frames = ["|", "/", "-", "\\"];
+
+  const stopSpinnerLine = () => {
+    if (spinnerTimer) {
+      clearInterval(spinnerTimer);
+      spinnerTimer = null;
+    }
+    if (activeLine && typeof process !== "undefined" && process?.stdout?.write) {
+      process.stdout.write("\n");
+      activeLine = false;
+    }
+  };
+
+  const renderLine = () => {
+    const frame = frames[currentFrameIndex % frames.length];
+    currentFrameIndex += 1;
+    const rawLine = `${frame} Polling ${currentJobId} (${currentStatus})`;
+    const paddedLine = rawLine.padEnd(lastRenderedLength, " ");
+    lastRenderedLength = paddedLine.length;
+    if (typeof process !== "undefined" && process?.stdout?.write) {
+      process.stdout.write(`\r${paddedLine}`);
+      activeLine = true;
+      return;
+    }
+    if (typeof logger?.log === "function") {
+      logger.log(rawLine);
+    }
+  };
+
+  const writeLine = (line) => {
+    stopSpinnerLine();
+    if (typeof logger?.log === "function") {
+      logger.log(line);
+    }
+  };
+
   return {
     start({ jobId, jobStatus }) {
-      lastStatus = jobStatus || null;
-      if (typeof logger?.log === "function") {
-        logger.log(`Polling ${jobId} (${jobStatus || "waiting"})`);
-      }
-    },
-    update({ jobId, jobStatus }) {
-      if (jobStatus === lastStatus) {
+      currentJobId = jobId || currentJobId;
+      currentStatus = jobStatus || currentStatus;
+      currentFrameIndex = 0;
+      if (typeof process !== "undefined" && process?.stdout?.write) {
+        renderLine();
+        spinnerTimer = setInterval(renderLine, DEFAULT_POLLING_SPINNER_INTERVAL_MS);
         return;
       }
-      lastStatus = jobStatus || null;
-      if (typeof logger?.log === "function") {
-        logger.log(`Polling ${jobId} (${jobStatus || "unknown"})`);
+      writeLine(`Polling ${currentJobId} (${currentStatus})`);
+    },
+    update({ jobStatus }) {
+      currentStatus = jobStatus || currentStatus;
+      if (!spinnerTimer && !(typeof process !== "undefined" && process?.stdout?.write)) {
+        writeLine(`Polling ${currentJobId} (${currentStatus})`);
       }
     },
     finish({ jobStatus, resultUrl }) {
-      if (typeof logger?.log === "function") {
-        logger.log(resultUrl
-          ? `Polling complete: ${jobStatus} - ${resultUrl}`
-          : `Polling complete: ${jobStatus}`);
-      }
+      currentStatus = jobStatus || currentStatus;
+      writeLine(resultUrl || `Polling complete: ${currentStatus}`);
     },
     timeout({ timeoutSeconds, jobStatus }) {
-      if (typeof logger?.log === "function") {
-        logger.log(`Polling stopped: timeout after ${timeoutSeconds}s (${jobStatus})`);
-      }
+      currentStatus = jobStatus || currentStatus;
+      writeLine(`Polling stopped: timeout after ${timeoutSeconds}s (${currentStatus})`);
     },
   };
 }
 
+function logTerminalAsyncResult(result, logger = console) {
+  if (typeof logger?.log !== "function" || !result || typeof result !== "object") {
+    return;
+  }
+  if (result.result_url) {
+    logger.log(String(result.result_url));
+    return;
+  }
+  logger.log(JSON.stringify(result, null, 2));
+}
+
 function composeProgressHandler({ onProgress, showLogs = false, logger = console } = {}) {
   const logHandler = showLogs ? createSdkLoggerProgressHandler(logger) : null;
   if (!logHandler) {
@@ -521,7 +626,14 @@ async function estimateDurationFromFile(file) {
   }
 
   try {
-    const bytes = new Uint8Array(await file.slice(0, headerLength).arrayBuffer());
+    let bytes;
+    if (typeof file?.readSlice === "function") {
+      bytes = new Uint8Array(await file.readSlice(0, headerLength));
+    } else if (typeof file?.slice === "function") {
+      bytes = new Uint8Array(await file.slice(0, headerLength).arrayBuffer());
+    } else {
+      return estimateDurationFromSize(file?.size);
+    }
     const type = typeFromNameOrContentType(file?.name, file?.type || contentTypeFromName(file?.name));
     const duration = type === "wav"
       ? parseWavDuration(bytes)
@@ -538,6 +650,30 @@ async function estimateDurationFromFile(file) {
   return estimateDurationFromSize(file?.size);
 }
 
+async function fileFromPath(pathValue) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  const stats = await fs.stat(pathValue);
+  const name = path.basename(pathValue);
+  return {
+    name,
+    size: stats.size,
+    type: contentTypeFromName(name),
+    path: pathValue,
+    async readSlice(start, end) {
+      const handle = await fs.open(pathValue, "r");
+      try {
+        const length = Math.max(0, end - start);
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, start);
+        return buffer.subarray(0, bytesRead);
+      } finally {
+        await handle.close();
+      }
+    },
+  };
+}
+
 function makeFile(parts, name, type) {
   if (typeof File !== "undefined") {
     return new File(parts, name, { type });
@@ -554,14 +690,12 @@ async function normalizeFile(input, fallbackName = "audio.mp3") {
     && typeof input.name === "string"
     && Number.isFinite(Number(input.size))
     && typeof input.type === "string"
-    && typeof input.slice === "function"
+    && (typeof input.readSlice === "function" || typeof input.slice === "function")
   ) {
     return input;
   }
   if (typeof input === "string") {
-    throw new TranscribeAPIError("Worker SDK does not support local file paths. Use a Blob, File, bytes, or remote URL.", {
-      code: "unsupported_file_path",
-    });
+    return fileFromPath(input);
   }
   if (typeof File !== "undefined" && input instanceof File) {
     return input;
@@ -572,7 +706,7 @@ async function normalizeFile(input, fallbackName = "audio.mp3") {
   if (input?.data instanceof Uint8Array || input?.data instanceof ArrayBuffer) {
     return makeFile([input.data], input.name || fallbackName, input.type || contentTypeFromName(input.name || fallbackName));
   }
-  throw new TranscribeAPIError("Invalid file. Provide a File, Blob, or { data, name, type }.");
+  throw new TranscribeAPIError("Invalid file. Provide a path, File, Blob, or { data, name, type }.");
 }
 
 async function parseApiResponse(response) {
@@ -581,21 +715,22 @@ async function parseApiResponse(response) {
   try {
     data = text ? JSON.parse(text) : {};
   } catch {
-    data = { raw: text };
+    data = text;
   }
   if (!response.ok) {
-    const message = data.message || data.error || text || `HTTP ${response.status}`;
-    const extra = { ...data };
+    const body = data && typeof data === "object" ? data : {};
+    const message = body.message || body.error || text || `HTTP ${response.status}`;
+    const extra = { ...body };
     delete extra.message;
     delete extra.error;
     delete extra.code;
     throw new TranscribeAPIError(message, {
       status: response.status,
-      code: data.code || null,
+      code: body.code || null,
       extra,
       response: {
         message,
-        ...(data.code ? { code: data.code } : {}),
+        ...(body.code ? { code: body.code } : {}),
         ...extra,
       },
     });
@@ -611,6 +746,68 @@ function normalizeHeaders(headers = {}) {
   );
 }
 
+function isNodeStreamBody(body) {
+  return Boolean(body && typeof body === "object" && typeof body.pipe === "function");
+}
+
+async function putNodeStream(upload, streamBody, headers) {
+  const http = await import("node:http");
+  const https = await import("node:https");
+  const { pipeline } = await import("node:stream/promises");
+  const target = new URL(upload.url || upload);
+  const transport = target.protocol === "https:" ? https : http;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finishResolve = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(value);
+    };
+    const finishReject = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      reject(error);
+    };
+    const request = transport.request(target, {
+      method: "PUT",
+      headers,
+      agent: false,
+    }, (response) => {
+      response.resume();
+      response.on("error", finishReject);
+      response.on("end", () => {
+        finishResolve({
+          ok: response.statusCode >= 200 && response.statusCode < 300,
+          status: response.statusCode || 0,
+          headers: {
+            get(name) {
+              const value = response.headers[String(name || "").toLowerCase()];
+              return Array.isArray(value) ? value[0] : value || null;
+            },
+          },
+        });
+      });
+    });
+
+    request.on("error", finishReject);
+    request.on("socket", (socket) => {
+      socket.on("error", finishReject);
+    });
+    request.setTimeout(120000, () => {
+      request.destroy(new Error("stream_upload_timeout"));
+    });
+    if (typeof streamBody.on === "function") {
+      streamBody.on("error", finishReject);
+    }
+    pipeline(streamBody, request).catch(finishReject);
+  });
+}
+
 async function putObjectWithRetry(upload, body, {
   onProgress,
   loadedOffset = 0,
@@ -618,17 +815,39 @@ async function putObjectWithRetry(upload, body, {
   contentLength = null,
   progressMeta = null,
   debugContext = null,
+  uploadLimiter = null,
 } = {}) {
-  const response = await retry(async () => {
-    const resolvedBody = typeof body === "function" ? await body() : body;
-    const putResponse = await fetch(upload.url || upload, {
-      method: "PUT",
-      headers: normalizeHeaders({
+  const response = await retry(async (attemptIndex) => {
+    const executePut = async () => {
+      const resolvedBody = typeof body === "function" ? await body() : body;
+      const headers = normalizeHeaders({
         ...(upload.headers || {}),
         ...(contentLength !== null ? { "Content-Length": contentLength } : {}),
-      }),
-      body: resolvedBody,
-    });
+        ...(typeof body === "function" ? { Connection: "close" } : {}),
+      });
+      const putResponse = isNodeStreamBody(resolvedBody)
+        ? await putNodeStream(upload, resolvedBody, headers)
+        : await fetch(upload.url || upload, {
+          method: "PUT",
+          headers,
+          body: resolvedBody,
+        });
+      if (!putResponse.ok) {
+        throw new TranscribeAPIError(`R2 upload failed with HTTP ${putResponse.status}.`, {
+          status: putResponse.status,
+          code: "upload_failed",
+          extra: {
+            ...(progressMeta || {}),
+            ...(debugContext || {}),
+            content_length: contentLength,
+          },
+        });
+      }
+      return putResponse;
+    };
+    const putResponse = uploadLimiter?.withToken
+      ? await uploadLimiter.withToken(executePut)
+      : await executePut();
     if (!putResponse.ok) {
       throw new TranscribeAPIError(`R2 upload failed with HTTP ${putResponse.status}.`, {
         status: putResponse.status,
@@ -645,7 +864,6 @@ async function putObjectWithRetry(upload, body, {
     attempts: 5,
     baseDelayMs: 1000,
   });
-
   const transferredBytes = Number(
     contentLength
     ?? body?.size
@@ -663,6 +881,14 @@ async function putObjectWithRetry(upload, body, {
   return response;
 }
 
+async function openFileBody(file, start = 0, end = null) {
+  if (!file?.path) {
+    return file;
+  }
+  const fs = await import("node:fs");
+  return fs.createReadStream(file.path, end === null ? { start } : { start, end: end - 1 });
+}
+
 async function runWithConcurrency(items, concurrency, worker) {
   let index = 0;
   const workerCount = Math.max(1, Math.min(items.length || 1, concurrency));
@@ -679,6 +905,41 @@ async function runWithConcurrency(items, concurrency, worker) {
   await Promise.all(workers);
 }
 
+function createUploadConcurrencyLimiter(concurrency) {
+  const maxConcurrency = Math.max(1, normalizeUploadConcurrency(concurrency));
+  let active = 0;
+  const waiters = [];
+
+  const acquire = async () => {
+    if (active < maxConcurrency) {
+      active += 1;
+      return;
+    }
+    await new Promise((resolve) => waiters.push(resolve));
+    active += 1;
+  };
+
+  const release = () => {
+    active = Math.max(0, active - 1);
+    const next = waiters.shift();
+    if (next) {
+      next();
+    }
+  };
+
+  return {
+    concurrency: maxConcurrency,
+    async withToken(operation) {
+      await acquire();
+      try {
+        return await operation();
+      } finally {
+        release();
+      }
+    },
+  };
+}
+
 function multipartCompleteXml(parts) {
   const rows = parts
     .sort((a, b) => a.partNumber - b.partNumber)
@@ -689,18 +950,19 @@ function multipartCompleteXml(parts) {
 
 async function uploadMultipart(upload, file, {
   onProgress,
-  multipartConcurrency = DEFAULT_MULTIPART_CONCURRENCY,
+  uploadConcurrency = DEFAULT_UPLOAD_CONCURRENCY,
   onConcurrencyChange = null,
+  uploadLimiter = null,
 } = {}) {
   const completed = [];
-  const completedPartNumbers = new Set();
-  let completedBytes = 0;
   const totalParts = upload.parts.length;
-  const concurrency = normalizeMultipartConcurrency(multipartConcurrency);
+  const completedPartNumbers = new Set(completed.map((part) => part.partNumber));
+  let completedBytes = 0;
+  const concurrency = normalizeUploadConcurrency(uploadConcurrency);
   let targetConcurrency = concurrency;
   let activeWorkers = 0;
   let fatalError = null;
-  const pendingParts = [...upload.parts];
+  const pendingParts = upload.parts.filter((part) => !completedPartNumbers.has(part.part_number));
   const partAttempts = new Map();
 
   const workers = Array.from({ length: concurrency }, async (_, workerIndex) => {
@@ -715,7 +977,6 @@ async function uploadMultipart(upload, file, {
         await sleep(MULTIPART_IDLE_WAIT_MS);
         continue;
       }
-
       const part = pendingParts.shift();
       if (!part) {
         if (!activeWorkers) {
@@ -732,7 +993,7 @@ async function uploadMultipart(upload, file, {
       try {
         const response = await putObjectWithRetry(
           { url: part.url },
-          file.slice(start, end),
+          file.path ? (() => openFileBody(file, start, end)) : file.slice(start, end),
           {
             onProgress: null,
             loadedOffset: 0,
@@ -750,6 +1011,7 @@ async function uploadMultipart(upload, file, {
               range_start: start,
               range_end_exclusive: end,
             },
+            uploadLimiter,
           },
         );
         const etag = response.headers.get("ETag") || response.headers.get("etag");
@@ -773,7 +1035,8 @@ async function uploadMultipart(upload, file, {
       } catch (error) {
         const attempts = (partAttempts.get(part.part_number) || 0) + 1;
         partAttempts.set(part.part_number, attempts);
-        if (isRetryableError(error) && attempts < MAX_MULTIPART_ADAPTIVE_ATTEMPTS) {
+        const retryable = isRetryableError(error);
+        if (retryable && attempts < MAX_MULTIPART_ADAPTIVE_ATTEMPTS) {
           const previousConcurrency = targetConcurrency;
           targetConcurrency = Math.max(1, Math.floor(targetConcurrency / 2));
           pendingParts.push(part);
@@ -794,19 +1057,32 @@ async function uploadMultipart(upload, file, {
           await sleep(Math.min(10000, 1000 * (2 ** Math.min(attempts - 1, 3))));
           continue;
         }
-        fatalError = new TranscribeAPIError(`Multipart upload failed for part ${part.part_number}/${totalParts}.`, {
-          status: error?.status || null,
-          code: error?.code || "multipart_part_upload_failed",
-          extra: {
-            cause_error: error?.error || error?.message || String(error),
-            cause_code: error?.code || error?.cause?.code || null,
-            cause_status: error?.status || null,
+        fatalError = new TranscribeAPIError(
+          `Multipart upload failed for part ${part.part_number}/${totalParts}.`,
+          {
+            status: error?.status || null,
+            code: error?.code || "multipart_part_upload_failed",
+            extra: {
+              cause_error: error?.error || error?.message || String(error),
+              cause_code: error?.code || error?.cause?.code || null,
+              cause_status: error?.status || null,
+              upload_type: "multipart",
+              part_number: part.part_number,
+              total_parts: totalParts,
+              chunk_bytes: chunkSize,
+              completed_bytes_before_failure: completedBytes,
+              multipart_concurrency: targetConcurrency,
+              file_name: file?.name || null,
+              file_size: file?.size || null,
+              range_start: start,
+              range_end_exclusive: end,
+              attempts,
+            },
           },
-        });
+        );
         activeWorkers -= 1;
         return;
       }
-
       activeWorkers -= 1;
     }
   });
@@ -837,7 +1113,8 @@ async function uploadUsingInstructions(upload, file, options = {}) {
   if (upload.type === "multipart") {
     return uploadMultipart(upload, file, options);
   }
-  return putObjectWithRetry(upload, file, {
+  const body = file.path ? (() => openFileBody(file)) : file;
+  return putObjectWithRetry(upload, body, {
     onProgress: options.onProgress,
     loadedOffset: 0,
     totalBytes: file.size,
@@ -850,6 +1127,7 @@ async function uploadUsingInstructions(upload, file, options = {}) {
       file_name: file?.name || null,
       file_size: file?.size || null,
     },
+    uploadLimiter: options.uploadLimiter || null,
   });
 }
 
@@ -866,66 +1144,6 @@ function assertBatchLimits(totalFiles, totalSizeBytes) {
   }
 }
 
-class BigFileJob {
-  constructor(client, file, createResponse, options) {
-    this.client = client;
-    this.file = file;
-    this.createResponse = createResponse;
-    this.referenceId = options.referenceId || defaultReferenceId(0);
-    this.jobId = createResponse.job_id;
-    this.jobStatus = createResponse.job_status;
-    this.model = createResponse.model || options.model || null;
-    this.uploadInfo = uploadFromResponse(createResponse, this.referenceId);
-    this.options = options;
-  }
-
-  async upload({ onProgress } = {}) {
-    const progress = onProgress || this.options.onProgress;
-    if (!this.uploadInfo) {
-      return this.createResponse;
-    }
-    await uploadUsingInstructions(this.uploadInfo, this.file, {
-      onProgress: progress,
-      multipartConcurrency: this.options.multipartConcurrency,
-      onConcurrencyChange: (event) => {
-        if (typeof onProgress === "function" || typeof this.options.onProgress === "function") {
-          (onProgress || this.options.onProgress)({
-            uploadType: "multipart",
-            event: "adaptive_concurrency",
-            previousConcurrency: event.previousConcurrency,
-            multipartConcurrency: event.nextConcurrency,
-            partNumber: event.partNumber,
-            attempts: event.attempts,
-            error: event.error,
-          });
-        }
-      },
-    });
-    const completion = await this.client.jobs.complete(this.jobId);
-    emitProgress(progress, {
-      event: "upload_completed",
-      jobId: this.jobId,
-      response: completion,
-      suppressLog: Boolean(this.client.polling),
-    });
-    return completion;
-  }
-}
-
-class RemoteBigFileJob {
-  constructor(client, createResponse, options) {
-    this.client = client;
-    this.createResponse = createResponse;
-    this.jobId = createResponse.job_id;
-    this.jobStatus = createResponse.job_status;
-    this.model = createResponse.model || options.model || null;
-  }
-
-  async upload() {
-    return this.createResponse;
-  }
-}
-
 class BatchJob {
   constructor(client, files, createResponse, options) {
     this.client = client;
@@ -949,6 +1167,7 @@ class BatchJob {
     const totalBytes = this.files.reduce((sum, item) => sum + Number(item?.file?.size || 0), 0);
     const loadedByReferenceId = new Map();
     const uploadableFiles = this.files.filter((item) => item.file);
+    const uploadLimiter = this.options.uploadLimiter || createUploadConcurrencyLimiter(this.options.uploadConcurrency);
 
     emitProgress(progress, {
       event: "upload_started",
@@ -958,10 +1177,7 @@ class BatchJob {
       totalBytes,
     });
 
-    for (const item of this.files) {
-      if (!item.file) {
-        continue;
-      }
+    await runWithConcurrency(uploadableFiles, this.options.uploadConcurrency, async (item) => {
       const upload = this.uploadsByReferenceId.get(item.referenceId);
       if (!upload) {
         throw new TranscribeAPIError(`Missing upload instructions for \`${item.referenceId}\`.`, {
@@ -969,6 +1185,8 @@ class BatchJob {
         });
       }
       await uploadUsingInstructions(upload, item.file, {
+        uploadConcurrency: this.options.uploadConcurrency,
+        uploadLimiter,
         onProgress: (event) => {
           const fileLoaded = Math.max(0, Math.min(Number(event?.loaded || 0), Number(item.file.size || 0)));
           loadedByReferenceId.set(item.referenceId, fileLoaded);
@@ -987,8 +1205,7 @@ class BatchJob {
           });
         },
       });
-    }
-
+    });
     const completion = await this.client.jobs.complete(this.jobId);
     emitProgress(progress, {
       event: "upload_completed",
@@ -998,7 +1215,7 @@ class BatchJob {
       batchTotal: totalBytes,
       totalFiles: this.files.length,
       uploadFiles: uploadableFiles.length,
-      suppressLog: Boolean(this.client.polling),
+      suppressLog: Boolean(this.client.polling) && !TERMINAL_JOB_STATUSES.has(String(completion?.job_status || "")),
     });
     return completion;
   }
@@ -1008,7 +1225,7 @@ export class TranscribeAPI {
   constructor({
     apiKey,
     baseUrl = DEFAULT_BASE_URL,
-    multipartConcurrency = DEFAULT_MULTIPART_CONCURRENCY,
+    uploadConcurrency = DEFAULT_UPLOAD_CONCURRENCY,
     showLogs = false,
     logger = console,
     polling = null,
@@ -1019,13 +1236,10 @@ export class TranscribeAPI {
 
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/+$/, "");
-    this.multipartConcurrency = normalizeMultipartConcurrency(multipartConcurrency);
+    this.uploadConcurrency = normalizeUploadConcurrency(uploadConcurrency);
     this.showLogs = Boolean(showLogs);
     this.logger = logger || console;
     this.polling = normalizePollingConfig(polling);
-    this.batch = {
-      transcribe: (options) => this.transcribeMany(options),
-    };
     this.jobs = {
       createBigFile: (options) => this.createBigFileJob(options),
       createBatch: (options) => this.createBatchJob(options),
@@ -1063,16 +1277,16 @@ export class TranscribeAPI {
     }
 
     const startedAt = Date.now();
-    const pollingLogger = showLogs ? createSdkPollingLogger(logger) : null;
+    const spinner = showLogs ? createSdkPollingLogger(logger) : null;
     let lastJob = initialJob || null;
-    pollingLogger?.start({
+    spinner?.start({
       jobId,
       jobStatus: lastJob?.job_status || "waiting",
     });
 
     while (!TERMINAL_JOB_STATUSES.has(String(lastJob?.job_status || ""))) {
       if (effectivePolling.timeout !== null && (Date.now() - startedAt) >= effectivePolling.timeout * 1000) {
-        pollingLogger?.timeout({
+        spinner?.timeout({
           timeoutSeconds: effectivePolling.timeout,
           jobStatus: lastJob?.job_status || "unknown",
         });
@@ -1089,13 +1303,12 @@ export class TranscribeAPI {
 
       await sleep(effectivePolling.interval * 1000);
       lastJob = await this.jobs.get(jobId);
-      pollingLogger?.update({
-        jobId,
+      spinner?.update({
         jobStatus: lastJob?.job_status || "unknown",
       });
     }
 
-    pollingLogger?.finish({
+    spinner?.finish({
       jobStatus: lastJob?.job_status || "unknown",
       resultUrl: lastJob?.result_url || null,
     });
@@ -1103,96 +1316,152 @@ export class TranscribeAPI {
   }
 
   async transcribe({
-    file,
+    files,
     webhookUrl,
     onProgress,
     showLogs,
     logger,
     language,
-    task,
-    vadFilter,
-    initialPrompt,
-    vttGranularity,
     exclude,
-    multipartConcurrency,
+    uploadConcurrency,
   } = {}) {
     const progress = composeProgressHandler({
       onProgress,
       showLogs: showLogs ?? this.showLogs,
       logger: logger ?? this.logger,
     });
-    if (isRemoteFileInput(file)) {
-      const job = await this.createBigFileJob({
-        file,
-        webhookUrl,
-        onProgress: progress,
-        showLogs: false,
-        multipartConcurrency,
-      });
-      const result = await job.upload({ onProgress: progress });
-      if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
-        return this.waitForJobCompletion(result.job_id, {
-          polling: this.polling,
-          showLogs: showLogs ?? this.showLogs,
+    if (isFilesInput(files)) {
+      if (files.length === 0) {
+        throw new TranscribeAPIError("Transcribe requires at least one file.", {
+          code: "invalid_files",
+        });
+      }
+      if (files.length > 1) {
+        for (let index = 0; index < files.length; index += 1) {
+          if (!String(files[index]?.reference_id || "").trim()) {
+            throw new TranscribeAPIError(`files[${index}].reference_id is required when sending multiple files.`, {
+              code: "missing_reference_id",
+            });
+          }
+        }
+        return this._transcribeAsync({
+          files,
+          webhookUrl,
+          durationEstimateSec: undefined,
+          onProgress,
+          showLogs,
           logger: logger ?? this.logger,
-          initialJob: result,
+          uploadConcurrency,
+          language,
+          exclude,
         });
       }
-      return result;
-    }
 
-    const normalizedFile = await normalizeFile(file);
-    const estimatedDurationSec = await estimateDurationFromFile(normalizedFile);
-    if (normalizedFile.size > MAX_SYNC_AUDIO_BYTES || estimatedDurationSec > MAX_SYNC_AUDIO_SECONDS) {
-      const job = await this.createBigFileJob({
-        file: normalizedFile,
-        webhookUrl,
-        durationEstimateSec: estimatedDurationSec,
-        onProgress: progress,
-        showLogs: false,
-        multipartConcurrency,
-      });
-      const result = await job.upload({ onProgress: progress });
-      if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
-        return this.waitForJobCompletion(result.job_id, {
-          polling: this.polling,
-          showLogs: showLogs ?? this.showLogs,
+      const normalizedItem = normalizeBatchInputItem(files[0], 0);
+      const normalizedSingleFile = normalizedItem.url ? null : await normalizeFile(normalizedItem.file);
+      const estimatedDurationSec = normalizedItem.url
+        ? normalizedItem.durationEstimateSec
+        : (normalizedItem.durationEstimateSec || await estimateDurationFromFile(normalizedSingleFile));
+      const effectiveLanguage = normalizedItem.hasLanguage ? normalizedItem.language : normalizeLanguageCode(language);
+      const isAsync = files.length > 1
+        || Boolean(normalizedItem.url)
+        || Boolean(webhookUrl)
+        || (
+          normalizedSingleFile
+          && (
+            normalizedSingleFile.size > MAX_SYNC_AUDIO_BYTES
+            || estimatedDurationSec > MAX_SYNC_AUDIO_SECONDS
+          )
+        );
+      if (isAsync) {
+        return this._transcribeAsync({
+          files,
+          webhookUrl,
+          durationEstimateSec: estimatedDurationSec,
+          onProgress,
+          showLogs,
           logger: logger ?? this.logger,
-          initialJob: result,
+          uploadConcurrency,
+          language,
+          exclude,
         });
       }
-      return result;
+
+      return this.transcribeDirect({
+        file: normalizedSingleFile,
+        referenceId: normalizedItem.referenceId,
+        language: effectiveLanguage,
+        exclude,
+        webhookUrl,
+        showLogs: showLogs ?? this.showLogs,
+        logger: logger ?? this.logger,
+      });
     }
+    throw new TranscribeAPIError("`transcribe` requires a `files` array.", {
+      code: "invalid_files",
+    });
+  }
 
-    return this.transcribeDirect({
-      file: normalizedFile,
+  async _transcribeAsync({
+    files,
+    webhookUrl,
+    durationEstimateSec,
+    onProgress,
+    showLogs,
+    logger,
+    uploadConcurrency,
+    language,
+    exclude,
+  } = {}) {
+    const progress = composeProgressHandler({
+      onProgress,
+      showLogs: showLogs ?? this.showLogs,
+      logger: logger ?? this.logger,
+    });
+    const job = await this.createBatchJob({
+      files,
+      webhookUrl,
+      durationEstimateSec,
+      onProgress: progress,
+      showLogs: false,
+      uploadConcurrency,
       language,
-      task,
-      vadFilter,
-      initialPrompt,
-      vttGranularity,
       exclude,
     });
+    const result = await job.upload({ onProgress: progress });
+    if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
+      return this.waitForJobCompletion(result.job_id, {
+        polling: this.polling,
+        showLogs: showLogs ?? this.showLogs,
+        logger: logger ?? this.logger,
+        initialJob: result,
+      });
+    }
+    if ((showLogs ?? this.showLogs) && TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
+      logTerminalAsyncResult(result, logger ?? this.logger);
+    }
+    return result;
   }
 
   async transcribeDirect({
     file,
+    referenceId,
     language,
-    task,
-    vadFilter,
-    initialPrompt,
-    vttGranularity,
     exclude,
+    webhookUrl,
+    showLogs = false,
+    logger = console,
   } = {}) {
     const normalizedFile = await normalizeFile(file);
+    const directFile = normalizedFile.path
+      ? makeFile([await normalizedFile.readSlice(0, normalizedFile.size)], normalizedFile.name, normalizedFile.type)
+      : normalizedFile;
     const form = new FormData();
-    form.set("file", normalizedFile, normalizedFile.name);
+    if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
+    form.set("file", directFile, directFile.name);
     if (language) form.set("language", language);
-    if (task) form.set("task", task);
-    if (vadFilter !== undefined) form.set("vad_filter", String(Boolean(vadFilter)));
-    if (initialPrompt) form.set("initial_prompt", initialPrompt);
-    if (vttGranularity) form.set("vtt_granularity", vttGranularity);
     if (exclude) form.set("exclude", Array.isArray(exclude) ? exclude.join(",") : exclude);
+    if (webhookUrl) form.set("webhook_url", webhookUrl);
 
     const response = await fetch(`${this.baseUrl}/transcribe`, {
       method: "POST",
@@ -1201,7 +1470,19 @@ export class TranscribeAPI {
       },
       body: form,
     });
-    return parseApiResponse(response);
+    const result = await parseApiResponse(response);
+    if (this.polling && result && typeof result === "object" && result.job_status && !TERMINAL_JOB_STATUSES.has(String(result.job_status))) {
+      return this.waitForJobCompletion(result.job_id, {
+        polling: this.polling,
+        showLogs,
+        logger,
+        initialJob: result,
+      });
+    }
+    if (showLogs && typeof logger?.log === "function") {
+      logger.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    }
+    return result;
   }
 
   async transcribeMany({
@@ -1211,31 +1492,21 @@ export class TranscribeAPI {
     onProgress,
     showLogs,
     logger,
-    multipartConcurrency,
+    uploadConcurrency,
+    language,
+    exclude,
   } = {}) {
-    const progress = composeProgressHandler({
-      onProgress,
-      showLogs: showLogs ?? this.showLogs,
-      logger: logger ?? this.logger,
-    });
-    const job = await this.createBatchJob({
+    return this._transcribeAsync({
       files,
       webhookUrl,
       durationEstimateSec,
-      onProgress: progress,
-      showLogs: false,
-      multipartConcurrency,
+      onProgress,
+      showLogs,
+      logger: logger ?? this.logger,
+      uploadConcurrency,
+      language,
+      exclude,
     });
-    const result = await job.upload({ onProgress: progress });
-    if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
-      return this.waitForJobCompletion(result.job_id, {
-        polling: this.polling,
-        showLogs: showLogs ?? this.showLogs,
-        logger: logger ?? this.logger,
-        initialJob: result,
-      });
-    }
-    return result;
   }
 
   async createBigFileJob({
@@ -1245,57 +1516,20 @@ export class TranscribeAPI {
     onProgress,
     showLogs,
     logger,
-    multipartConcurrency,
+    uploadConcurrency,
+    language,
+    exclude,
   } = {}) {
-    const progress = composeProgressHandler({
+    return this.createBatchJob({
+      files: [file],
+      webhookUrl,
+      durationEstimateSec,
       onProgress,
-      showLogs: showLogs ?? this.showLogs,
+      showLogs,
       logger: logger ?? this.logger,
-    });
-    const normalizedConcurrency = normalizeMultipartConcurrency(multipartConcurrency ?? this.multipartConcurrency);
-    if (isRemoteFileInput(file)) {
-      const response = await this.requestJson("/transcribe", {
-        method: "POST",
-        body: {
-          files: [{
-            reference_id: defaultReferenceId(0),
-            url: file.url,
-          }],
-          ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
-        },
-        retryable: true,
-      });
-      return new RemoteBigFileJob(this, response, {
-        onProgress: progress,
-        multipartConcurrency: normalizedConcurrency,
-      });
-    }
-
-    const normalizedFile = await normalizeFile(file);
-    const estimate = durationEstimateSec || await estimateDurationFromFile(normalizedFile);
-    const response = await this.requestJson("/transcribe", {
-      method: "POST",
-      body: {
-        files: [
-          estimate > MAX_SYNC_AUDIO_SECONDS || normalizedFile.size > MAX_SYNC_AUDIO_BYTES
-            ? uploadDescriptorForFile(defaultReferenceId(0), normalizedFile)
-            : { reference_id: defaultReferenceId(0) },
-        ],
-        ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
-      },
-      retryable: true,
-    });
-    emitProgress(progress, {
-      event: "upload_urls_received",
-      jobId: response.job_id,
-      jobStatus: response.job_status,
-      uploadCount: normalizeResponseUploads(response).length,
-      totalFiles: 1,
-    });
-    return new BigFileJob(this, normalizedFile, response, {
-      onProgress: progress,
-      multipartConcurrency: normalizedConcurrency,
-      referenceId: defaultReferenceId(0),
+      uploadConcurrency,
+      language,
+      exclude,
     });
   }
 
@@ -1306,13 +1540,16 @@ export class TranscribeAPI {
     onProgress,
     showLogs,
     logger,
-    multipartConcurrency,
+    uploadConcurrency,
+    language,
+    exclude,
   } = {}) {
     const progress = composeProgressHandler({
       onProgress,
       showLogs: showLogs ?? this.showLogs,
       logger: logger ?? this.logger,
     });
+    const normalizedLanguage = normalizeLanguageCode(language);
     if (!Array.isArray(files) || files.length === 0) {
       throw new TranscribeAPIError("Batch upload requires at least one file.", { code: "invalid_files" });
     }
@@ -1328,17 +1565,21 @@ export class TranscribeAPI {
           referenceId: item.referenceId,
           url: item.url,
           durationEstimateSec: item.durationEstimateSec || durationEstimateSec || null,
+          hasLanguage: item.hasLanguage,
+          language: item.language,
         });
         continue;
       }
 
-      const fileValue = await normalizeFile(item.file, `file_${String(index + 1).padStart(6, "0")}.mp3`);
-      assertSupportedBatchFormat(fileValue);
+      const file = await normalizeFile(item.file, `file_${String(index + 1).padStart(6, "0")}.mp3`);
+      assertSupportedBatchFormat(file);
       normalizedBatchItems.push({
-        file: fileValue,
-        referenceId: item.referenceId,
+        file,
+        referenceId: item.referenceId || defaultReferenceId(index),
         url: null,
-        durationEstimateSec: item.durationEstimateSec || await estimateDurationFromFile(fileValue),
+        durationEstimateSec: item.durationEstimateSec || await estimateDurationFromFile(file),
+        hasLanguage: item.hasLanguage,
+        language: item.language,
       });
     }
 
@@ -1350,12 +1591,18 @@ export class TranscribeAPI {
         files: normalizedBatchItems.map((item) => (
           item.url
             ? {
-              reference_id: item.referenceId,
+              ...(item.referenceId ? { reference_id: item.referenceId } : {}),
               url: item.url,
+              ...(item.hasLanguage ? { language: item.language } : {}),
+            }
+            : {
+              ...uploadDescriptorForFile(item.referenceId, item.file),
+              ...(item.hasLanguage ? { language: item.language } : {}),
             }
-            : uploadDescriptorForFile(item.referenceId, item.file)
         )),
+        ...(normalizedLanguage ? { language: normalizedLanguage } : {}),
         ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
+        ...(exclude ? { exclude: Array.isArray(exclude) ? exclude.join(",") : exclude } : {}),
       },
       retryable: true,
     });
@@ -1369,7 +1616,7 @@ export class TranscribeAPI {
     return new BatchJob(this, normalizedBatchItems, response, {
       onProgress: progress,
       webhookUrl,
-      multipartConcurrency: normalizeMultipartConcurrency(multipartConcurrency ?? this.multipartConcurrency),
+      uploadConcurrency: normalizeUploadConcurrency(uploadConcurrency ?? this.uploadConcurrency),
     });
   }
 }