@transcribe-api/sdk 0.1.2 → 0.1.5

package/index.js

@@ -1,100 +1,109 @@
-const DEFAULT_BASE_URL = "https://api.transcribeapi.com/v1";
-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 DEFAULT_BASE_URL = "https://api.transcribeapi.com/v1";
+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 = 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 MULTIPART_RESUME_STATE_VERSION = 1;
 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.";
-
-export class TranscribeAPIError extends Error {
-  constructor(error, { status = null, code = null, extra = null, response = null } = {}) {
-    super(error);
-    this.name = "TranscribeAPIError";
-    this.status = status;
-    this.code = code;
-    this.error = error;
-    this.response = response;
-    if (extra && typeof extra === "object") {
-      for (const [key, value] of Object.entries(extra)) {
-        if (key === "status" || key === "stack" || key === "name") {
-          continue;
-        }
-        this[key] = value;
-      }
-    }
-  }
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function extractErrorInfo(error) {
-  return {
-    name: error?.name || null,
-    message: error?.message || String(error),
-    code: error?.code || error?.cause?.code || null,
-    status: error?.status || null,
-    cause_message: error?.cause?.message || null,
-  };
-}
-
-function isRetryableError(error) {
-  const code = String(error?.code || error?.cause?.code || "");
-  if (
-    code === "ECONNRESET"
-    || code === "ETIMEDOUT"
-    || code === "ECONNREFUSED"
-    || code === "EPIPE"
-    || code === "UND_ERR_SOCKET"
-    || code === "UND_ERR_CONNECT_TIMEOUT"
-    || code === "ERR_SSL_SSLV3_ALERT_BAD_RECORD_MAC"
-  ) {
-    return true;
-  }
-  if (String(error?.message || "").includes("fetch failed")) {
-    return true;
-  }
-  return !error?.status || error.status === 429 || error.status >= 500;
-}
-
-async function retry(operation, { attempts = 3, baseDelayMs = 250 } = {}) {
-  let lastError;
-  for (let index = 0; index < attempts; index += 1) {
-    try {
-      return await operation(index);
-    } catch (error) {
-      lastError = error;
-      const retryable = isRetryableError(error);
-      if (!retryable || index === attempts - 1) {
-        throw error;
-      }
-      await sleep(baseDelayMs * (2 ** index));
-    }
-  }
-  throw lastError;
-}
-
-function normalizeMultipartConcurrency(value) {
-  if (value === undefined || value === null || value === "") {
-    return DEFAULT_MULTIPART_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",
-    });
-  }
-  return Math.min(parsed, MAX_MULTIPART_CONCURRENCY);
+
+export class TranscribeAPIError extends Error {
+  constructor(message, { status = null, code = null, extra = null, response = null } = {}) {
+    super(message);
+    this.name = "TranscribeAPIError";
+    this.status = status;
+    this.code = code;
+    this.response = response || { message, ...(code ? { code } : {}) };
+    if (extra && typeof extra === "object") {
+      for (const [key, value] of Object.entries(extra)) {
+        if (key === "status" || key === "stack" || key === "name" || key === "message" || key === "code") {
+          continue;
+        }
+        this[key] = value;
+      }
+    }
+  }
+
+  toJSON() {
+    return {
+      message: this.message,
+      ...(this.code ? { code: this.code } : {}),
+      ...Object.fromEntries(
+        Object.entries(this)
+          .filter(([key]) => !["name", "status", "code", "response"].includes(key)),
+      ),
+    };
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function extractErrorInfo(error) {
+  return {
+    name: error?.name || null,
+    message: error?.message || String(error),
+    code: error?.code || error?.cause?.code || null,
+    status: error?.status || null,
+    cause_message: error?.cause?.message || null,
+  };
+}
+
+function isRetryableError(error) {
+  const code = String(error?.code || error?.cause?.code || "");
+  if (
+    code === "ECONNRESET"
+    || code === "ETIMEDOUT"
+    || code === "ECONNREFUSED"
+    || code === "EPIPE"
+    || code === "UND_ERR_SOCKET"
+    || code === "UND_ERR_CONNECT_TIMEOUT"
+    || code === "ERR_SSL_SSLV3_ALERT_BAD_RECORD_MAC"
+  ) {
+    return true;
+  }
+  if (String(error?.message || "").includes("fetch failed")) {
+    return true;
+  }
+  return !error?.status || error.status === 429 || error.status >= 500;
+}
+
+async function retry(operation, { attempts = 3, baseDelayMs = 250 } = {}) {
+  let lastError;
+  for (let index = 0; index < attempts; index += 1) {
+    try {
+      return await operation(index);
+    } catch (error) {
+      lastError = error;
+      const retryable = isRetryableError(error);
+      if (!retryable || index === attempts - 1) {
+        throw error;
+      }
+      await sleep(baseDelayMs * (2 ** index));
+    }
+  }
+  throw lastError;
+}
+
+function normalizeUploadConcurrency(value) {
+  if (value === undefined || value === null || value === "") {
+    return DEFAULT_UPLOAD_CONCURRENCY;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new TranscribeAPIError("`uploadConcurrency` must be an integer >= 1.", {
+      code: "invalid_upload_concurrency",
+    });
+  }
+  return Math.min(parsed, MAX_UPLOAD_CONCURRENCY);
 }
 
 function normalizePollingConfig(polling) {
@@ -133,212 +142,97 @@ function normalizePollingConfig(polling) {
     timeout,
   };
 }
-
-function isNodePathFile(file) {
-  return Boolean(file?.path && typeof file.path === "string");
-}
-
-function multipartResumeStatePath(filePath) {
-  return `${filePath}.transcribe-upload.json`;
-}
-
-function normalizeCompletedParts(parts) {
-  if (!Array.isArray(parts)) {
-    return [];
-  }
-  const deduped = new Map();
-  for (const part of parts) {
-    const partNumber = Number(part?.part_number ?? part?.partNumber);
-    const etag = String(part?.etag || "").trim();
-    if (!Number.isInteger(partNumber) || partNumber < 1 || !etag) {
-      continue;
-    }
-    deduped.set(partNumber, {
-      part_number: partNumber,
-      etag,
-    });
-  }
-  return Array.from(deduped.values()).sort((a, b) => a.part_number - b.part_number);
-}
-
-function serializeUploadForResume(upload) {
-  if (!upload || typeof upload !== "object") {
-    return null;
-  }
-  if (upload.type === "multipart") {
-    return {
-      type: "multipart",
-      key: upload.key || null,
-      upload_id: upload.upload_id || null,
-      part_size: Number(upload.part_size || 0),
-    };
-  }
-  if (upload.type === "put") {
-    return {
-      type: "put",
-      key: upload.key || null,
-      headers: upload.headers || {},
-    };
-  }
-  return null;
-}
-
-async function readMultipartResumeState(file, { baseUrl } = {}) {
-  if (!isNodePathFile(file)) {
-    return null;
-  }
-  try {
-    const fs = await import("node:fs/promises");
-    const raw = await fs.readFile(multipartResumeStatePath(file.path), "utf8");
-    const parsed = JSON.parse(raw);
-    if (
-      Number(parsed?.version) !== MULTIPART_RESUME_STATE_VERSION
-      || String(parsed?.file_path || "") !== String(file.path)
-      || Number(parsed?.file_size || 0) !== Number(file.size || 0)
-      || String(parsed?.file_name || "") !== String(file.name || "")
-    ) {
-      return null;
-    }
-    if (baseUrl && String(parsed?.api_base_url || "") !== String(baseUrl)) {
-      return null;
-    }
-    const upload = serializeUploadForResume(parsed.upload);
-    if (!upload) {
-      return null;
-    }
-    return {
-      version: MULTIPART_RESUME_STATE_VERSION,
-      api_base_url: String(parsed.api_base_url || ""),
-      job_id: String(parsed.job_id || ""),
-      model: parsed.model || null,
-      file_path: String(parsed.file_path || ""),
-      file_name: String(parsed.file_name || ""),
-      file_size: Number(parsed.file_size || 0),
-      upload,
-      completed_parts: normalizeCompletedParts(parsed.completed_parts),
-    };
-  } catch {
-    return null;
-  }
-}
-
-async function writeMultipartResumeState(file, state) {
-  if (!isNodePathFile(file) || !state) {
-    return;
-  }
-  const fs = await import("node:fs/promises");
-  await fs.writeFile(
-    multipartResumeStatePath(file.path),
-    JSON.stringify(state, null, 2),
-    "utf8",
-  );
-}
-
-async function deleteMultipartResumeState(file) {
-  if (!isNodePathFile(file)) {
-    return;
-  }
-  try {
-    const fs = await import("node:fs/promises");
-    await fs.unlink(multipartResumeStatePath(file.path));
-  } catch {
-    // Ignore missing or inaccessible state files.
-  }
-}
-
-function buildMultipartResumeState({ baseUrl, jobId, model, file, upload, completedParts }) {
-  return {
-    version: MULTIPART_RESUME_STATE_VERSION,
-    api_base_url: baseUrl,
-    job_id: jobId,
-    model: model || null,
-    file_path: file.path,
-    file_name: file.name,
-    file_size: file.size,
-    upload: serializeUploadForResume(upload),
-    completed_parts: normalizeCompletedParts(completedParts),
-  };
-}
-
-function contentTypeFromName(name = "") {
-  const lower = String(name).toLowerCase();
-  if (lower.endsWith(".mp3")) return "audio/mpeg";
-  if (lower.endsWith(".mpeg")) return "audio/mpeg";
-  if (lower.endsWith(".mpga")) return "audio/mpeg";
-  if (lower.endsWith(".wav")) return "audio/wav";
-  if (lower.endsWith(".m4a")) return "audio/mp4";
-  if (lower.endsWith(".webm")) return "audio/webm";
-  return "application/octet-stream";
-}
-
-function isRemoteFileInput(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 defaultReferenceId(index) {
-  return `file_${String(index + 1).padStart(6, "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`.", {
-      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 hasFile = Object.prototype.hasOwnProperty.call(item, "file");
-  const hasUrl = typeof item.url === "string" && item.url.trim();
-  if (hasFile && hasUrl) {
-    throw new TranscribeAPIError(`files[${index}] must include either \`file\` or \`url\`, not both.`, {
-      code: "invalid_batch_item",
-    });
-  }
-  if (!hasFile && !hasUrl) {
-    throw new TranscribeAPIError(`files[${index}] must include either \`file\` or \`url\`.`, {
-      code: "invalid_batch_item",
-    });
-  }
-
-  return {
-    referenceId,
-    file: hasFile ? item.file : null,
-    url: hasUrl ? item.url.trim() : null,
-    durationEstimateSec: item.durationEstimateSec || item.duration_estimate_sec || null,
-  };
-}
-
-function uploadDescriptorForFile(referenceId, file) {
-  const descriptor = { reference_id: referenceId };
-  if (Number(file?.size || 0) >= MULTIPART_UPLOAD_THRESHOLD_BYTES) {
-    descriptor.size_bytes = Number(file.size || 0);
-  }
-  return descriptor;
-}
-
-function normalizeResponseUploads(response) {
-  if (Array.isArray(response?.uploads)) {
-    return response.uploads;
-  }
-  if (response?.upload) {
-    return [{
-      reference_id: response.reference_id || defaultReferenceId(0),
-      upload: response.upload,
-    }];
-  }
-  return [];
-}
-
+
+function contentTypeFromName(name = "") {
+  const lower = String(name).toLowerCase();
+  if (lower.endsWith(".mp3")) return "audio/mpeg";
+  if (lower.endsWith(".mpeg")) return "audio/mpeg";
+  if (lower.endsWith(".mpga")) return "audio/mpeg";
+  if (lower.endsWith(".wav")) return "audio/wav";
+  if (lower.endsWith(".m4a")) return "audio/mp4";
+  if (lower.endsWith(".webm")) return "audio/webm";
+  return "application/octet-stream";
+}
+
+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 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 either `file` or `url`.", {
+      code: "invalid_batch_item",
+    });
+  }
+
+  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();
+  if (hasFile && hasUrl) {
+    throw new TranscribeAPIError(`files[${index}] must include either \`file\` or \`url\`, not both.`, {
+      code: "invalid_batch_item",
+    });
+  }
+  if (!hasFile && !hasUrl) {
+    throw new TranscribeAPIError(`files[${index}] must include either \`file\` or \`url\`.`, {
+      code: "invalid_batch_item",
+    });
+  }
+
+  return {
+    referenceId,
+    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 = {};
+  if (referenceId) descriptor.reference_id = referenceId;
+  if (Number(file?.size || 0) >= MULTIPART_UPLOAD_THRESHOLD_BYTES) {
+    descriptor.size_bytes = Number(file.size || 0);
+  }
+  return descriptor;
+}
+
+function normalizeResponseUploads(response) {
+  if (Array.isArray(response?.uploads)) {
+    return response.uploads;
+  }
+  if (response?.upload) {
+    return [{
+      reference_id: response.reference_id || defaultReferenceId(0),
+      upload: response.upload,
+    }];
+  }
+  return [];
+}
+
 function uploadFromResponse(response, referenceId) {
   if (response?.upload) {
     return response.upload;
@@ -374,11 +268,14 @@ 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);
@@ -387,7 +284,9 @@ function createSdkLoggerProgressHandler(logger = console) {
 
   const writeProgress = (line) => {
     if (typeof process !== "undefined" && process?.stdout?.write) {
-      process.stdout.write(`\r${line}`);
+      const paddedLine = line.padEnd(lastRenderedLength, " ");
+      lastRenderedLength = paddedLine.length;
+      process.stdout.write(`\r${paddedLine}`);
       activeProgressLine = true;
       return;
     }
@@ -401,7 +300,7 @@ function createSdkLoggerProgressHandler(logger = console) {
       return;
     }
     if (event.event === "upload_started") {
-      writeLine(`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") {
@@ -412,11 +311,17 @@ function createSdkLoggerProgressHandler(logger = console) {
       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") {
       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)}`);
@@ -487,9 +392,7 @@ function createSdkPollingLogger(logger = console) {
     },
     finish({ jobStatus, resultUrl }) {
       currentStatus = jobStatus || currentStatus;
-      writeLine(resultUrl
-        ? `Polling complete: ${currentStatus} - ${resultUrl}`
-        : `Polling complete: ${currentStatus}`);
+      writeLine(resultUrl || `Polling complete: ${currentStatus}`);
     },
     timeout({ timeoutSeconds, jobStatus }) {
       currentStatus = jobStatus || currentStatus;
@@ -498,6 +401,17 @@ function createSdkPollingLogger(logger = console) {
   };
 }
 
+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) {
@@ -508,836 +422,742 @@ function composeProgressHandler({ onProgress, showLogs = false, logger = console
     emitProgress(onProgress, event);
   };
 }
-
-function assertSupportedBatchFormat(file) {
-  const lowerName = String(file?.name || "").toLowerCase();
-  const lowerType = String(file?.type || contentTypeFromName(file?.name)).toLowerCase();
-
-  if (lowerName.endsWith(".mp4") || lowerType === "video/mp4") {
-    throw new TranscribeAPIError(BATCH_MP4_UNSUPPORTED_MESSAGE, { code: "unsupported_batch_format" });
-  }
-
-  if (
-    lowerName.endsWith(".mp3")
-    || lowerName.endsWith(".mpeg")
-    || lowerName.endsWith(".mpga")
-    || lowerName.endsWith(".m4a")
-    || lowerName.endsWith(".wav")
-    || lowerName.endsWith(".webm")
-    || lowerType.includes("audio/mpeg")
-    || lowerType.includes("mpga")
-    || lowerType.includes("audio/mp4")
-    || lowerType.includes("audio/x-m4a")
-    || lowerType.includes("audio/wav")
-    || lowerType.includes("audio/wave")
-    || lowerType.includes("audio/webm")
-    || lowerType.includes("video/webm")
-  ) {
-    return;
-  }
-
-  throw new TranscribeAPIError(BATCH_UNSUPPORTED_MESSAGE, { code: "unsupported_batch_format" });
-}
-
-function estimateDurationFromSize(sizeBytes) {
-  return Math.max(1, Math.ceil(Number(sizeBytes || 0) / 16000));
-}
-
-function ascii(bytes, offset, length) {
-  return Array.from(bytes.slice(offset, offset + length), (byte) => String.fromCharCode(byte)).join("");
-}
-
-function readUint32(bytes, offset, littleEndian = false) {
-  return new DataView(bytes.buffer, bytes.byteOffset + offset, 4).getUint32(0, littleEndian);
-}
-
-function readUint64(bytes, offset) {
-  const high = readUint32(bytes, offset);
-  const low = readUint32(bytes, offset + 4);
-  return high * 2 ** 32 + low;
-}
-
-function syncSafeInteger(bytes, offset) {
-  return ((bytes[offset] & 0x7f) << 21)
-    | ((bytes[offset + 1] & 0x7f) << 14)
-    | ((bytes[offset + 2] & 0x7f) << 7)
-    | (bytes[offset + 3] & 0x7f);
-}
-
-function id3Offset(bytes) {
-  if (bytes.length >= 10 && ascii(bytes, 0, 3) === "ID3") {
-    return 10 + syncSafeInteger(bytes, 6);
-  }
-  return 0;
-}
-
-const MP3_BITRATES = {
-  V1L3: [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
-  V2L3: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
-};
-
-const MP3_SAMPLE_RATES = {
-  3: [44100, 48000, 32000],
-  2: [22050, 24000, 16000],
-  0: [11025, 12000, 8000],
-};
-
-function mp3FrameInfoAt(bytes, offset) {
-  if (offset + 4 > bytes.length || bytes[offset] !== 0xff || (bytes[offset + 1] & 0xe0) !== 0xe0) {
-    return null;
-  }
-
-  const versionBits = (bytes[offset + 1] >> 3) & 0x03;
-  const layerBits = (bytes[offset + 1] >> 1) & 0x03;
-  const bitrateIndex = (bytes[offset + 2] >> 4) & 0x0f;
-  const sampleRateIndex = (bytes[offset + 2] >> 2) & 0x03;
-  const padding = (bytes[offset + 2] >> 1) & 0x01;
-  if (versionBits === 1 || layerBits !== 1 || bitrateIndex === 0 || bitrateIndex === 15 || sampleRateIndex === 3) {
-    return null;
-  }
-
-  const sampleRate = MP3_SAMPLE_RATES[versionBits]?.[sampleRateIndex];
-  const bitrateKbps = versionBits === 3
-    ? MP3_BITRATES.V1L3[bitrateIndex]
-    : MP3_BITRATES.V2L3[bitrateIndex];
-  if (!sampleRate || !bitrateKbps) {
-    return null;
-  }
-
-  const bitrate = bitrateKbps * 1000;
-  const frameLength = Math.floor(((versionBits === 3 ? 144 : 72) * bitrate) / sampleRate + padding);
-  if (frameLength <= 0) {
-    return null;
-  }
-
-  return {
-    bitrate,
-    sampleRate,
-    frameLength,
-  };
-}
-
-function findMp3Frame(bytes, startOffset = 0) {
-  for (let offset = Math.max(0, startOffset); offset < bytes.length - 4; offset += 1) {
-    const info = mp3FrameInfoAt(bytes, offset);
-    if (info) {
-      return { offset, ...info };
-    }
-  }
-  return null;
-}
-
-function parseMp3Duration(bytes, objectSize) {
-  const offset = id3Offset(bytes);
-  const firstFrame = findMp3Frame(bytes, offset);
-  if (!firstFrame) {
-    return null;
-  }
-  const audioBytes = Math.max(0, Number(objectSize || bytes.length) - firstFrame.offset);
-  const duration = (audioBytes * 8) / firstFrame.bitrate;
-  return Number.isFinite(duration) && duration > 0 ? duration : null;
-}
-
-function parseWavDuration(bytes) {
-  if (bytes.length < 44 || ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WAVE") {
-    return null;
-  }
-
-  let offset = 12;
-  let byteRate = 0;
-  let dataSize = 0;
-  while (offset + 8 <= bytes.length) {
-    const chunkId = ascii(bytes, offset, 4);
-    const chunkSize = readUint32(bytes, offset + 4, true);
-    if (chunkId === "fmt " && offset + 20 <= bytes.length) {
-      byteRate = readUint32(bytes, offset + 16, true);
-    } else if (chunkId === "data") {
-      dataSize = chunkSize;
-      break;
-    }
-    offset += 8 + chunkSize + (chunkSize % 2);
-  }
-
-  if (!byteRate || !dataSize) {
-    return null;
-  }
-  return dataSize / byteRate;
-}
-
-function parseMp4Duration(bytes) {
-  for (let offset = 0; offset + 32 < bytes.length; offset += 1) {
-    if (ascii(bytes, offset + 4, 4) !== "mvhd") {
-      continue;
-    }
-    const size = readUint32(bytes, offset);
-    if (size < 32 || offset + size > bytes.length + 8) {
-      continue;
-    }
-    const version = bytes[offset + 8];
-    if (version === 0 && offset + 28 <= bytes.length) {
-      const timescale = readUint32(bytes, offset + 20);
-      const duration = readUint32(bytes, offset + 24);
-      return timescale > 0 ? duration / timescale : null;
-    }
-    if (version === 1 && offset + 40 <= bytes.length) {
-      const timescale = readUint32(bytes, offset + 28);
-      const duration = readUint64(bytes, offset + 32);
-      return timescale > 0 ? duration / timescale : null;
-    }
-  }
-  return null;
-}
-
-function typeFromNameOrContentType(name = "", contentType = "") {
-  const lowerName = String(name || "").toLowerCase();
-  const lowerType = String(contentType || "").toLowerCase();
-  if (lowerType.includes("wav") || lowerName.endsWith(".wav")) {
-    return "wav";
-  }
-  if (
-    lowerType.includes("mp4")
-    || lowerType.includes("m4a")
-    || lowerType.includes("audio/x-m4a")
-    || lowerName.endsWith(".m4a")
-  ) {
-    return "m4a";
-  }
-  return "mp3";
-}
-
-async function estimateDurationFromFile(file) {
-  const headerLength = Math.min(Number(file?.size || 0), 2 * 1024 * 1024);
-  if (!headerLength) {
-    return estimateDurationFromSize(file?.size);
-  }
-
-  try {
-    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)
-      : type === "m4a"
-        ? parseMp4Duration(bytes)
-        : parseMp3Duration(bytes, file.size);
-    if (Number.isFinite(duration) && duration > 0) {
-      return Math.max(1, Math.ceil(duration));
-    }
-  } catch {
-    // Fall back to the coarse size heuristic when metadata parsing fails.
-  }
-
-  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 });
-  }
-  const blob = new Blob(parts, { type });
-  Object.defineProperty(blob, "name", { value: name });
-  return blob;
-}
-
-async function normalizeFile(input, fallbackName = "audio.mp3") {
-  if (
-    input
-    && typeof input === "object"
-    && typeof input.name === "string"
-    && Number.isFinite(Number(input.size))
-    && typeof input.type === "string"
-    && (typeof input.readSlice === "function" || typeof input.slice === "function")
-  ) {
-    return input;
-  }
-  if (typeof input === "string") {
-    return fileFromPath(input);
-  }
-  if (typeof File !== "undefined" && input instanceof File) {
-    return input;
-  }
-  if (input instanceof Blob) {
-    return input.name ? input : makeFile([input], fallbackName, input.type || contentTypeFromName(fallbackName));
-  }
-  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 path, File, Blob, or { data, name, type }.");
-}
-
-async function parseApiResponse(response) {
-  const text = await response.text();
-  let data = {};
-  try {
-    data = text ? JSON.parse(text) : {};
-  } catch {
-    data = { raw: text };
-  }
-  if (!response.ok) {
-    throw new TranscribeAPIError(data.error || text || `HTTP ${response.status}`, {
-      status: response.status,
-      code: data.code || null,
-      extra: data,
-      response: data,
-    });
-  }
-  return data;
-}
-
-function normalizeHeaders(headers = {}) {
-  return Object.fromEntries(
-    Object.entries(headers)
-      .filter(([, value]) => value !== undefined && value !== null)
-      .map(([key, value]) => [key, String(value)]),
-  );
-}
-
-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,
-  totalBytes = 0,
-  contentLength = null,
-  progressMeta = null,
-  debugContext = null,
-} = {}) {
-  const response = await retry(async (attemptIndex) => {
-    const resolvedBody = typeof body === "function" ? await body() : body;
-    const headers = normalizeHeaders({
-      ...(upload.headers || {}),
-      ...(contentLength !== null ? { "Content-Length": contentLength } : {}),
-      ...(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;
-  }, {
-    attempts: 5,
-    baseDelayMs: 1000,
-  });
-  const transferredBytes = Number(
-    contentLength
-    ?? body?.size
-    ?? body?.byteLength
-    ?? 0,
-  );
-  const loaded = loadedOffset + transferredBytes;
-  if (onProgress) {
-    onProgress({
-      loaded,
-      total: totalBytes || loaded,
-      ...(progressMeta || {}),
-    });
-  }
-  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));
-  const workers = Array.from({ length: workerCount }, async () => {
-    while (true) {
-      const current = index;
-      index += 1;
-      if (current >= items.length) {
-        return;
-      }
-      await worker(items[current], current);
-    }
-  });
-  await Promise.all(workers);
-}
-
-function multipartCompleteXml(parts) {
-  const rows = parts
-    .sort((a, b) => a.partNumber - b.partNumber)
-    .map((part) => `<Part><PartNumber>${part.partNumber}</PartNumber><ETag>${part.etag}</ETag></Part>`)
-    .join("");
-  return `<CompleteMultipartUpload>${rows}</CompleteMultipartUpload>`;
-}
-
-async function uploadMultipart(upload, file, {
-  onProgress,
-  multipartConcurrency = DEFAULT_MULTIPART_CONCURRENCY,
-  resumeState = null,
-  onPartComplete = null,
-  onConcurrencyChange = null,
-} = {}) {
-  const completed = normalizeCompletedParts(resumeState?.completed_parts).map((part) => ({
-    partNumber: part.part_number,
-    etag: part.etag,
-  }));
-  const totalParts = upload.parts.length;
-  const completedPartNumbers = new Set(completed.map((part) => part.partNumber));
-  let completedBytes = completed.reduce((total, part) => {
-    const start = (part.partNumber - 1) * upload.part_size;
-    const end = Math.min(file.size, start + upload.part_size);
-    return total + Math.max(0, end - start);
-  }, 0);
-  const concurrency = normalizeMultipartConcurrency(multipartConcurrency);
-  let targetConcurrency = concurrency;
-  let activeWorkers = 0;
-  let fatalError = null;
-  const pendingParts = upload.parts.filter((part) => !completedPartNumbers.has(part.part_number));
-  const partAttempts = new Map();
-
-  if (onProgress && completedBytes > 0) {
-    onProgress({
-      loaded: completedBytes,
-      total: file.size,
-      uploadType: "multipart",
-      totalParts,
-      multipartConcurrency: targetConcurrency,
-      resumed: true,
-    });
-  }
-
-  const workers = Array.from({ length: concurrency }, async (_, workerIndex) => {
-    while (true) {
-      if (fatalError) {
-        return;
-      }
-      if (completedPartNumbers.size >= totalParts) {
-        return;
-      }
-      if (workerIndex >= targetConcurrency) {
-        await sleep(MULTIPART_IDLE_WAIT_MS);
-        continue;
-      }
-      const part = pendingParts.shift();
-      if (!part) {
-        if (!activeWorkers) {
-          return;
-        }
-        await sleep(MULTIPART_IDLE_WAIT_MS);
-        continue;
-      }
-
-      activeWorkers += 1;
-      const start = (part.part_number - 1) * upload.part_size;
-      const end = Math.min(file.size, start + upload.part_size);
-      const chunkSize = end - start;
-      try {
-        const response = await putObjectWithRetry(
-          { url: part.url },
-          file.path ? (() => openFileBody(file, start, end)) : file.slice(start, end),
-          {
-            onProgress: null,
-            loadedOffset: 0,
-            totalBytes: file.size,
-            contentLength: chunkSize,
-            progressMeta: {
-              uploadType: "multipart",
-              partNumber: part.part_number,
-              totalParts,
-              chunkBytes: chunkSize,
-            },
-            debugContext: {
-              file_name: file?.name || null,
-              file_size: file?.size || null,
-              range_start: start,
-              range_end_exclusive: end,
-            },
-          },
-        );
-        const etag = response.headers.get("ETag") || response.headers.get("etag");
-        completed.push({
-          partNumber: part.part_number,
-          etag,
-        });
-        completedPartNumbers.add(part.part_number);
-        completedBytes += chunkSize;
-        if (onPartComplete) {
-          try {
-            await onPartComplete({
-              partNumber: part.part_number,
-              etag,
-              completedParts: completed,
-            });
-          } catch {
-            // Resume-state persistence is best-effort.
-          }
-        }
-        if (onProgress) {
-          onProgress({
-            loaded: completedBytes,
-            total: file.size,
-            uploadType: "multipart",
-            partNumber: part.part_number,
-            totalParts,
-            chunkBytes: chunkSize,
-            multipartConcurrency: targetConcurrency,
-          });
-        }
-      } catch (error) {
-        const attempts = (partAttempts.get(part.part_number) || 0) + 1;
-        partAttempts.set(part.part_number, 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);
-          if (onConcurrencyChange && targetConcurrency !== previousConcurrency) {
-            try {
-              onConcurrencyChange({
-                previousConcurrency,
-                nextConcurrency: targetConcurrency,
-                partNumber: part.part_number,
-                attempts,
-                error: extractErrorInfo(error),
-              });
-            } catch {
-              // Ignore observer failures.
-            }
-          }
-          activeWorkers -= 1;
-          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,
-              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;
-    }
-  });
-
-  await Promise.all(workers);
-  if (fatalError) {
-    throw fatalError;
-  }
-
-  const completeResponse = await retry(async () => {
-    const response = await fetch(upload.complete_url, {
-      method: "POST",
-      headers: { "Content-Type": "application/xml" },
-      body: multipartCompleteXml(completed),
-    });
-    if (!response.ok) {
-      throw new TranscribeAPIError(`R2 multipart complete failed with HTTP ${response.status}.`, {
-        status: response.status,
-        code: "multipart_complete_failed",
-      });
-    }
-    return response;
-  });
-  return completeResponse;
-}
-
-async function uploadUsingInstructions(upload, file, options = {}) {
-  if (upload.type === "multipart") {
-    return uploadMultipart(upload, file, options);
-  }
-  const body = file.path ? (() => openFileBody(file)) : file;
-  return putObjectWithRetry(upload, body, {
-    onProgress: options.onProgress,
-    loadedOffset: 0,
-    totalBytes: file.size,
-    contentLength: file.size,
-    progressMeta: {
-      uploadType: "single_put",
-      chunkBytes: file.size,
-    },
-    debugContext: {
-      file_name: file?.name || null,
-      file_size: file?.size || null,
-    },
-  });
-}
-
-function assertBatchLimits(totalFiles, totalSizeBytes) {
-  if (totalFiles > MAX_BATCH_FILES) {
-    throw new TranscribeAPIError(`Batch jobs support up to ${MAX_BATCH_FILES} files.`, {
-      code: "too_many_files",
-    });
-  }
-  if (totalSizeBytes > MAX_BATCH_TOTAL_SIZE_BYTES) {
-    throw new TranscribeAPIError("Batch jobs support up to 10GB total.", {
-      code: "batch_too_large",
-    });
-  }
-}
-
-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;
-    this.resumeState = options.resumeState || null;
-    this.resumeWriteChain = Promise.resolve();
-  }
-
-  async persistResumeState(completedParts = this.resumeState?.completed_parts || []) {
-    if (!isNodePathFile(this.file) || this.uploadInfo?.type !== "multipart") {
-      return;
-    }
-    const state = buildMultipartResumeState({
-      baseUrl: this.client.baseUrl,
-      jobId: this.jobId,
-      model: this.model,
-      file: this.file,
-      upload: this.uploadInfo,
-      completedParts,
-    });
-    this.resumeState = state;
-    this.resumeWriteChain = this.resumeWriteChain
-      .catch(() => {})
-      .then(() => writeMultipartResumeState(this.file, state))
-      .catch(() => {});
-    await this.resumeWriteChain;
-  }
-
-  async clearResumeState() {
-    await this.resumeWriteChain.catch(() => {});
-    await deleteMultipartResumeState(this.file);
-    this.resumeState = null;
-  }
-
-  async upload({ onProgress } = {}) {
-    const progress = onProgress || this.options.onProgress;
-    if (!this.uploadInfo) {
-      return this.createResponse;
+
+function assertSupportedBatchFormat(file) {
+  const lowerName = String(file?.name || "").toLowerCase();
+  const lowerType = String(file?.type || contentTypeFromName(file?.name)).toLowerCase();
+
+  if (lowerName.endsWith(".mp4") || lowerType === "video/mp4") {
+    throw new TranscribeAPIError(BATCH_MP4_UNSUPPORTED_MESSAGE, { code: "unsupported_batch_format" });
+  }
+
+  if (
+    lowerName.endsWith(".mp3")
+    || lowerName.endsWith(".mpeg")
+    || lowerName.endsWith(".mpga")
+    || lowerName.endsWith(".m4a")
+    || lowerName.endsWith(".wav")
+    || lowerName.endsWith(".webm")
+    || lowerType.includes("audio/mpeg")
+    || lowerType.includes("mpga")
+    || lowerType.includes("audio/mp4")
+    || lowerType.includes("audio/x-m4a")
+    || lowerType.includes("audio/wav")
+    || lowerType.includes("audio/wave")
+    || lowerType.includes("audio/webm")
+    || lowerType.includes("video/webm")
+  ) {
+    return;
+  }
+
+  throw new TranscribeAPIError(BATCH_UNSUPPORTED_MESSAGE, { code: "unsupported_batch_format" });
+}
+
+function estimateDurationFromSize(sizeBytes) {
+  return Math.max(1, Math.ceil(Number(sizeBytes || 0) / 16000));
+}
+
+function ascii(bytes, offset, length) {
+  return Array.from(bytes.slice(offset, offset + length), (byte) => String.fromCharCode(byte)).join("");
+}
+
+function readUint32(bytes, offset, littleEndian = false) {
+  return new DataView(bytes.buffer, bytes.byteOffset + offset, 4).getUint32(0, littleEndian);
+}
+
+function readUint64(bytes, offset) {
+  const high = readUint32(bytes, offset);
+  const low = readUint32(bytes, offset + 4);
+  return high * 2 ** 32 + low;
+}
+
+function syncSafeInteger(bytes, offset) {
+  return ((bytes[offset] & 0x7f) << 21)
+    | ((bytes[offset + 1] & 0x7f) << 14)
+    | ((bytes[offset + 2] & 0x7f) << 7)
+    | (bytes[offset + 3] & 0x7f);
+}
+
+function id3Offset(bytes) {
+  if (bytes.length >= 10 && ascii(bytes, 0, 3) === "ID3") {
+    return 10 + syncSafeInteger(bytes, 6);
+  }
+  return 0;
+}
+
+const MP3_BITRATES = {
+  V1L3: [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
+  V2L3: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+};
+
+const MP3_SAMPLE_RATES = {
+  3: [44100, 48000, 32000],
+  2: [22050, 24000, 16000],
+  0: [11025, 12000, 8000],
+};
+
+function mp3FrameInfoAt(bytes, offset) {
+  if (offset + 4 > bytes.length || bytes[offset] !== 0xff || (bytes[offset + 1] & 0xe0) !== 0xe0) {
+    return null;
+  }
+
+  const versionBits = (bytes[offset + 1] >> 3) & 0x03;
+  const layerBits = (bytes[offset + 1] >> 1) & 0x03;
+  const bitrateIndex = (bytes[offset + 2] >> 4) & 0x0f;
+  const sampleRateIndex = (bytes[offset + 2] >> 2) & 0x03;
+  const padding = (bytes[offset + 2] >> 1) & 0x01;
+  if (versionBits === 1 || layerBits !== 1 || bitrateIndex === 0 || bitrateIndex === 15 || sampleRateIndex === 3) {
+    return null;
+  }
+
+  const sampleRate = MP3_SAMPLE_RATES[versionBits]?.[sampleRateIndex];
+  const bitrateKbps = versionBits === 3
+    ? MP3_BITRATES.V1L3[bitrateIndex]
+    : MP3_BITRATES.V2L3[bitrateIndex];
+  if (!sampleRate || !bitrateKbps) {
+    return null;
+  }
+
+  const bitrate = bitrateKbps * 1000;
+  const frameLength = Math.floor(((versionBits === 3 ? 144 : 72) * bitrate) / sampleRate + padding);
+  if (frameLength <= 0) {
+    return null;
+  }
+
+  return {
+    bitrate,
+    sampleRate,
+    frameLength,
+  };
+}
+
+function findMp3Frame(bytes, startOffset = 0) {
+  for (let offset = Math.max(0, startOffset); offset < bytes.length - 4; offset += 1) {
+    const info = mp3FrameInfoAt(bytes, offset);
+    if (info) {
+      return { offset, ...info };
+    }
+  }
+  return null;
+}
+
+function parseMp3Duration(bytes, objectSize) {
+  const offset = id3Offset(bytes);
+  const firstFrame = findMp3Frame(bytes, offset);
+  if (!firstFrame) {
+    return null;
+  }
+  const audioBytes = Math.max(0, Number(objectSize || bytes.length) - firstFrame.offset);
+  const duration = (audioBytes * 8) / firstFrame.bitrate;
+  return Number.isFinite(duration) && duration > 0 ? duration : null;
+}
+
+function parseWavDuration(bytes) {
+  if (bytes.length < 44 || ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WAVE") {
+    return null;
+  }
+
+  let offset = 12;
+  let byteRate = 0;
+  let dataSize = 0;
+  while (offset + 8 <= bytes.length) {
+    const chunkId = ascii(bytes, offset, 4);
+    const chunkSize = readUint32(bytes, offset + 4, true);
+    if (chunkId === "fmt " && offset + 20 <= bytes.length) {
+      byteRate = readUint32(bytes, offset + 16, true);
+    } else if (chunkId === "data") {
+      dataSize = chunkSize;
+      break;
+    }
+    offset += 8 + chunkSize + (chunkSize % 2);
+  }
+
+  if (!byteRate || !dataSize) {
+    return null;
+  }
+  return dataSize / byteRate;
+}
+
+function parseMp4Duration(bytes) {
+  for (let offset = 0; offset + 32 < bytes.length; offset += 1) {
+    if (ascii(bytes, offset + 4, 4) !== "mvhd") {
+      continue;
     }
-    if (this.uploadInfo.type === "multipart" && isNodePathFile(this.file)) {
-      const persisted = this.resumeState || await readMultipartResumeState(this.file, {
-        baseUrl: this.client.baseUrl,
-      });
-      if (persisted?.job_id === this.jobId && persisted.upload?.type === "multipart") {
-        this.resumeState = persisted;
-        try {
-          const refreshed = await this.client.refreshBigFileUpload(this.jobId, {
-            upload: persisted.upload,
-          });
-          this.uploadInfo = refreshed;
-        } catch (error) {
-          if (error?.status === 404 || error?.code === "not_found") {
-            await this.clearResumeState();
-          }
-          if (error?.status === 409) {
-            const currentJob = await this.client.jobs.get(this.jobId);
-            this.jobStatus = currentJob?.job_status || this.jobStatus;
-            this.uploadInfo = null;
-            await this.clearResumeState();
-            return currentJob;
-          }
-          if (!(error?.status === 404 || error?.code === "not_found")) {
-            throw error;
-          }
-        }
-      }
-      await this.persistResumeState(this.resumeState?.completed_parts || []);
+    const size = readUint32(bytes, offset);
+    if (size < 32 || offset + size > bytes.length + 8) {
+      continue;
     }
-    await uploadUsingInstructions(this.uploadInfo, this.file, {
-      onProgress: progress,
-      multipartConcurrency: this.options.multipartConcurrency,
-      resumeState: this.resumeState,
-      onPartComplete: async ({ completedParts }) => {
-        if (!isNodePathFile(this.file) || this.uploadInfo?.type !== "multipart") {
-          return;
-        }
-        await this.persistResumeState(completedParts.map((part) => ({
-          part_number: part.partNumber,
-          etag: part.etag,
-        })));
-      },
-      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 version = bytes[offset + 8];
+    if (version === 0 && offset + 28 <= bytes.length) {
+      const timescale = readUint32(bytes, offset + 20);
+      const duration = readUint32(bytes, offset + 24);
+      return timescale > 0 ? duration / timescale : null;
+    }
+    if (version === 1 && offset + 40 <= bytes.length) {
+      const timescale = readUint32(bytes, offset + 28);
+      const duration = readUint64(bytes, offset + 32);
+      return timescale > 0 ? duration / timescale : null;
+    }
+  }
+  return null;
+}
+
+function typeFromNameOrContentType(name = "", contentType = "") {
+  const lowerName = String(name || "").toLowerCase();
+  const lowerType = String(contentType || "").toLowerCase();
+  if (lowerType.includes("wav") || lowerName.endsWith(".wav")) {
+    return "wav";
+  }
+  if (
+    lowerType.includes("mp4")
+    || lowerType.includes("m4a")
+    || lowerType.includes("audio/x-m4a")
+    || lowerName.endsWith(".m4a")
+  ) {
+    return "m4a";
+  }
+  return "mp3";
+}
+
+async function estimateDurationFromFile(file) {
+  const headerLength = Math.min(Number(file?.size || 0), 2 * 1024 * 1024);
+  if (!headerLength) {
+    return estimateDurationFromSize(file?.size);
+  }
+
+  try {
+    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)
+      : type === "m4a"
+        ? parseMp4Duration(bytes)
+        : parseMp3Duration(bytes, file.size);
+    if (Number.isFinite(duration) && duration > 0) {
+      return Math.max(1, Math.ceil(duration));
+    }
+  } catch {
+    // Fall back to the coarse size heuristic when metadata parsing fails.
+  }
+
+  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 });
+  }
+  const blob = new Blob(parts, { type });
+  Object.defineProperty(blob, "name", { value: name });
+  return blob;
+}
+
+async function normalizeFile(input, fallbackName = "audio.mp3") {
+  if (
+    input
+    && typeof input === "object"
+    && typeof input.name === "string"
+    && Number.isFinite(Number(input.size))
+    && typeof input.type === "string"
+    && (typeof input.readSlice === "function" || typeof input.slice === "function")
+  ) {
+    return input;
+  }
+  if (typeof input === "string") {
+    return fileFromPath(input);
+  }
+  if (typeof File !== "undefined" && input instanceof File) {
+    return input;
+  }
+  if (input instanceof Blob) {
+    return input.name ? input : makeFile([input], fallbackName, input.type || contentTypeFromName(fallbackName));
+  }
+  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 path, File, Blob, or { data, name, type }.");
+}
+
+async function parseApiResponse(response) {
+  const text = await response.text();
+  let data = {};
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = text;
+  }
+  if (!response.ok) {
+    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: body.code || null,
+      extra,
+      response: {
+        message,
+        ...(body.code ? { code: body.code } : {}),
+        ...extra,
       },
     });
-    await this.clearResumeState();
-    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 data;
+}
+
+function normalizeHeaders(headers = {}) {
+  return Object.fromEntries(
+    Object.entries(headers)
+      .filter(([, value]) => value !== undefined && value !== null)
+      .map(([key, value]) => [key, String(value)]),
+  );
+}
+
+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;
+            },
+          },
+        });
+      });
     });
-    return completion;
+
+    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,
+  totalBytes = 0,
+  contentLength = null,
+  progressMeta = null,
+  debugContext = null,
+  uploadLimiter = null,
+} = {}) {
+  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 } : {}),
+        ...(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,
+        code: "upload_failed",
+        extra: {
+          ...(progressMeta || {}),
+          ...(debugContext || {}),
+          content_length: contentLength,
+        },
+      });
+    }
+    return putResponse;
+  }, {
+    attempts: 5,
+    baseDelayMs: 1000,
+  });
+  const transferredBytes = Number(
+    contentLength
+    ?? body?.size
+    ?? body?.byteLength
+    ?? 0,
+  );
+  const loaded = loadedOffset + transferredBytes;
+  if (onProgress) {
+    onProgress({
+      loaded,
+      total: totalBytes || loaded,
+      ...(progressMeta || {}),
+    });
+  }
+  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));
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (true) {
+      const current = index;
+      index += 1;
+      if (current >= items.length) {
+        return;
+      }
+      await worker(items[current], current);
+    }
+  });
+  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();
+      }
+    },
+  };
 }
-
-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;
-    this.options = options;
-  }
-
-  async upload() {
-    return this.createResponse;
-  }
-}
-
-class BatchJob {
-  constructor(client, files, createResponse, options) {
-    this.client = client;
-    this.files = files;
-    this.createResponse = createResponse;
-    this.jobId = createResponse.job_id;
-    this.jobStatus = createResponse.job_status;
-    this.model = createResponse.model || options.model || null;
-    this.uploadsByReferenceId = new Map(
-      normalizeResponseUploads(createResponse).map((entry) => [entry.reference_id, entry.upload]),
-    );
-    this.options = options;
-  }
-
+
+function multipartCompleteXml(parts) {
+  const rows = parts
+    .sort((a, b) => a.partNumber - b.partNumber)
+    .map((part) => `<Part><PartNumber>${part.partNumber}</PartNumber><ETag>${part.etag}</ETag></Part>`)
+    .join("");
+  return `<CompleteMultipartUpload>${rows}</CompleteMultipartUpload>`;
+}
+
+async function uploadMultipart(upload, file, {
+  onProgress,
+  uploadConcurrency = DEFAULT_UPLOAD_CONCURRENCY,
+  onConcurrencyChange = null,
+  uploadLimiter = null,
+} = {}) {
+  const completed = [];
+  const totalParts = upload.parts.length;
+  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.filter((part) => !completedPartNumbers.has(part.part_number));
+  const partAttempts = new Map();
+
+  const workers = Array.from({ length: concurrency }, async (_, workerIndex) => {
+    while (true) {
+      if (fatalError) {
+        return;
+      }
+      if (completedPartNumbers.size >= totalParts) {
+        return;
+      }
+      if (workerIndex >= targetConcurrency) {
+        await sleep(MULTIPART_IDLE_WAIT_MS);
+        continue;
+      }
+      const part = pendingParts.shift();
+      if (!part) {
+        if (!activeWorkers) {
+          return;
+        }
+        await sleep(MULTIPART_IDLE_WAIT_MS);
+        continue;
+      }
+
+      activeWorkers += 1;
+      const start = (part.part_number - 1) * upload.part_size;
+      const end = Math.min(file.size, start + upload.part_size);
+      const chunkSize = end - start;
+      try {
+        const response = await putObjectWithRetry(
+          { url: part.url },
+          file.path ? (() => openFileBody(file, start, end)) : file.slice(start, end),
+          {
+            onProgress: null,
+            loadedOffset: 0,
+            totalBytes: file.size,
+            contentLength: chunkSize,
+            progressMeta: {
+              uploadType: "multipart",
+              partNumber: part.part_number,
+              totalParts,
+              chunkBytes: chunkSize,
+            },
+            debugContext: {
+              file_name: file?.name || null,
+              file_size: file?.size || null,
+              range_start: start,
+              range_end_exclusive: end,
+            },
+            uploadLimiter,
+          },
+        );
+        const etag = response.headers.get("ETag") || response.headers.get("etag");
+        completed.push({
+          partNumber: part.part_number,
+          etag,
+        });
+        completedPartNumbers.add(part.part_number);
+        completedBytes += chunkSize;
+        if (onProgress) {
+          onProgress({
+            loaded: completedBytes,
+            total: file.size,
+            uploadType: "multipart",
+            partNumber: part.part_number,
+            totalParts,
+            chunkBytes: chunkSize,
+            multipartConcurrency: targetConcurrency,
+          });
+        }
+      } catch (error) {
+        const attempts = (partAttempts.get(part.part_number) || 0) + 1;
+        partAttempts.set(part.part_number, 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);
+          if (onConcurrencyChange && targetConcurrency !== previousConcurrency) {
+            try {
+              onConcurrencyChange({
+                previousConcurrency,
+                nextConcurrency: targetConcurrency,
+                partNumber: part.part_number,
+                attempts,
+                error: extractErrorInfo(error),
+              });
+            } catch {
+              // Ignore observer failures.
+            }
+          }
+          activeWorkers -= 1;
+          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,
+              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;
+    }
+  });
+
+  await Promise.all(workers);
+  if (fatalError) {
+    throw fatalError;
+  }
+
+  const completeResponse = await retry(async () => {
+    const response = await fetch(upload.complete_url, {
+      method: "POST",
+      headers: { "Content-Type": "application/xml" },
+      body: multipartCompleteXml(completed),
+    });
+    if (!response.ok) {
+      throw new TranscribeAPIError(`R2 multipart complete failed with HTTP ${response.status}.`, {
+        status: response.status,
+        code: "multipart_complete_failed",
+      });
+    }
+    return response;
+  });
+  return completeResponse;
+}
+
+async function uploadUsingInstructions(upload, file, options = {}) {
+  if (upload.type === "multipart") {
+    return uploadMultipart(upload, file, options);
+  }
+  const body = file.path ? (() => openFileBody(file)) : file;
+  return putObjectWithRetry(upload, body, {
+    onProgress: options.onProgress,
+    loadedOffset: 0,
+    totalBytes: file.size,
+    contentLength: file.size,
+    progressMeta: {
+      uploadType: "single_put",
+      chunkBytes: file.size,
+    },
+    debugContext: {
+      file_name: file?.name || null,
+      file_size: file?.size || null,
+    },
+    uploadLimiter: options.uploadLimiter || null,
+  });
+}
+
+function assertBatchLimits(totalFiles, totalSizeBytes) {
+  if (totalFiles > MAX_BATCH_FILES) {
+    throw new TranscribeAPIError(`Batch jobs support up to ${MAX_BATCH_FILES} files.`, {
+      code: "too_many_files",
+    });
+  }
+  if (totalSizeBytes > MAX_BATCH_TOTAL_SIZE_BYTES) {
+    throw new TranscribeAPIError("Batch jobs support up to 10GB total.", {
+      code: "batch_too_large",
+    });
+  }
+}
+
+class BatchJob {
+  constructor(client, files, createResponse, options) {
+    this.client = client;
+    this.files = files;
+    this.createResponse = createResponse;
+    this.jobId = createResponse.job_id;
+    this.jobStatus = createResponse.job_status;
+    this.model = createResponse.model || options.model || null;
+    this.uploadsByReferenceId = new Map(
+      normalizeResponseUploads(createResponse).map((entry) => [entry.reference_id, entry.upload]),
+    );
+    this.options = options;
+  }
+
   async upload({ onProgress } = {}) {
     if (!this.uploadsByReferenceId.size) {
       return this.createResponse;
@@ -1347,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",
@@ -1356,17 +1177,16 @@ 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}\`.`, {
-          code: "missing_upload_instructions",
-        });
+      if (!upload) {
+        throw new TranscribeAPIError(`Missing upload instructions for \`${item.referenceId}\`.`, {
+          code: "missing_upload_instructions",
+        });
       }
       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);
@@ -1385,7 +1205,7 @@ class BatchJob {
           });
         },
       });
-    }
+    });
     const completion = await this.client.jobs.complete(this.jobId);
     emitProgress(progress, {
       event: "upload_completed",
@@ -1395,17 +1215,17 @@ 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;
   }
 }
-
+
 export class TranscribeAPI {
   constructor({
     apiKey,
     baseUrl = DEFAULT_BASE_URL,
-    multipartConcurrency = DEFAULT_MULTIPART_CONCURRENCY,
+    uploadConcurrency = DEFAULT_UPLOAD_CONCURRENCY,
     showLogs = false,
     logger = console,
     polling = null,
@@ -1416,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),
@@ -1432,29 +1249,20 @@ export class TranscribeAPI {
       result: (jobId) => this.requestJson(`/transcribe/${jobId}`),
     };
   }
-
-  async requestJson(path, { method = "GET", body = null, retryable = false } = {}) {
-    const run = async () => {
-      const response = await fetch(`${this.baseUrl}${path}`, {
-        method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          ...(body ? { "Content-Type": "application/json" } : {}),
-        },
-        body: body ? JSON.stringify(body) : null,
-      });
-      return parseApiResponse(response);
-    };
-    return retryable ? retry(run) : run();
-  }
-
-  async refreshBigFileUpload(jobId, { upload } = {}) {
-    const response = await this.requestJson(`/jobs/${jobId}/resume-upload`, {
-      method: "POST",
-      body: { upload },
-      retryable: true,
-    });
-    return response.upload;
+
+  async requestJson(path, { method = "GET", body = null, retryable = false } = {}) {
+    const run = async () => {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : null,
+      });
+      return parseApiResponse(response);
+    };
+    return retryable ? retry(run) : run();
   }
 
   async waitForJobCompletion(jobId, {
@@ -1506,120 +1314,104 @@ export class TranscribeAPI {
     });
     return lastJob;
   }
-
+
   async transcribe({
-    file,
+    files,
     webhookUrl,
     onProgress,
     showLogs,
     logger,
     language,
-    task,
-    vadFilter,
-    initialPrompt,
-    vttGranularity,
-    exclude,
-    multipartConcurrency,
+    exclude,
+    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,
+      });
     }
-
-    return this.transcribeDirect({
-      file: normalizedFile,
-      language,
-      task,
-      vadFilter,
-      initialPrompt,
-      vttGranularity,
-      exclude,
-    });
-  }
-
-  async transcribeDirect({
-    file,
-    language,
-    task,
-    vadFilter,
-    initialPrompt,
-    vttGranularity,
-    exclude,
-  } = {}) {
-    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", 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);
-
-    const response = await fetch(`${this.baseUrl}/transcribe`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: form,
-    });
-    return parseApiResponse(response);
-  }
-
-  async transcribeMany({
+    throw new TranscribeAPIError("`transcribe` requires a `files` array.", {
+      code: "invalid_files",
+    });
+  }
+
+  async _transcribeAsync({
     files,
     webhookUrl,
     durationEstimateSec,
     onProgress,
     showLogs,
     logger,
-    multipartConcurrency,
+    uploadConcurrency,
+    language,
+    exclude,
   } = {}) {
     const progress = composeProgressHandler({
       onProgress,
@@ -1632,7 +1424,9 @@ export class TranscribeAPI {
       durationEstimateSec,
       onProgress: progress,
       showLogs: false,
-      multipartConcurrency,
+      uploadConcurrency,
+      language,
+      exclude,
     });
     const result = await job.upload({ onProgress: progress });
     if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
@@ -1643,101 +1437,102 @@ export class TranscribeAPI {
         initialJob: result,
       });
     }
+    if ((showLogs ?? this.showLogs) && TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
+      logTerminalAsyncResult(result, logger ?? this.logger);
+    }
     return result;
   }
 
-  async createBigFileJob({
+  async transcribeDirect({
     file,
+    referenceId,
+    language,
+    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();
+    if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
+    form.set("file", directFile, directFile.name);
+    if (language) form.set("language", language);
+    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",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: form,
+    });
+    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({
+    files,
     webhookUrl,
     durationEstimateSec,
     onProgress,
     showLogs,
     logger,
-    multipartConcurrency,
+    uploadConcurrency,
+    language,
+    exclude,
   } = {}) {
-    const progress = composeProgressHandler({
+    return this._transcribeAsync({
+      files,
+      webhookUrl,
+      durationEstimateSec,
       onProgress,
-      showLogs: showLogs ?? this.showLogs,
+      showLogs,
       logger: logger ?? this.logger,
+      uploadConcurrency,
+      language,
+      exclude,
     });
-    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 resumeState = await readMultipartResumeState(normalizedFile, { baseUrl: this.baseUrl });
-    if (resumeState?.job_id && resumeState.upload?.type === "multipart") {
-      try {
-        const refreshedUpload = await this.refreshBigFileUpload(resumeState.job_id, {
-          upload: resumeState.upload,
-        });
-        const existingJob = await this.requestJson(`/transcribe/${resumeState.job_id}`, { retryable: true });
-        const currentStatus = existingJob?.job_status || "uploading";
-        return new BigFileJob(this, normalizedFile, {
-          job_id: resumeState.job_id,
-          job_status: currentStatus,
-          model: existingJob?.model || resumeState.model || null,
-          upload: currentStatus === "uploading" ? refreshedUpload : null,
-        }, {
-          onProgress: progress,
-          multipartConcurrency: normalizedConcurrency,
-          referenceId: defaultReferenceId(0),
-          resumeState,
-        });
-      } catch (error) {
-        if (error?.status === 404 || error?.code === "not_found") {
-          await deleteMultipartResumeState(normalizedFile);
-        } else {
-          throw error;
-        }
-      }
-    }
-    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,
+  }
+
+  async createBigFileJob({
+    file,
+    webhookUrl,
+    durationEstimateSec,
+    onProgress,
+    showLogs,
+    logger,
+    uploadConcurrency,
+    language,
+    exclude,
+  } = {}) {
+    return this.createBatchJob({
+      files: [file],
+      webhookUrl,
+      durationEstimateSec,
+      onProgress,
+      showLogs,
+      logger: logger ?? this.logger,
+      uploadConcurrency,
+      language,
+      exclude,
     });
-    const job = new BigFileJob(this, normalizedFile, response, {
-      onProgress: progress,
-      multipartConcurrency: normalizedConcurrency,
-      referenceId: defaultReferenceId(0),
-    });
-    if (uploadFromResponse(response, defaultReferenceId(0))?.type === "multipart" && isNodePathFile(normalizedFile)) {
-      await job.persistResumeState([]);
-    }
-    return job;
-  }
-
+  }
+
   async createBatchJob({
     files,
     webhookUrl,
@@ -1745,56 +1540,69 @@ 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" });
     }
-    assertBatchLimits(files.length, 0);
-    const normalizedItems = files.map((item, index) => normalizeBatchInputItem(item, index));
-
-    const normalizedBatchItems = [];
-    for (let index = 0; index < normalizedItems.length; index += 1) {
-      const item = normalizedItems[index];
-      if (isRemoteBatchItem(item)) {
-        normalizedBatchItems.push({
-          file: null,
-          referenceId: item.referenceId,
-          url: item.url,
-          durationEstimateSec: item.durationEstimateSec || durationEstimateSec || null,
-        });
-        continue;
-      }
-
-      const file = await normalizeFile(item.file, `file_${String(index + 1).padStart(6, "0")}.mp3`);
-      assertSupportedBatchFormat(file);
-      normalizedBatchItems.push({
-        file,
-        referenceId: item.referenceId,
-        url: null,
-        durationEstimateSec: item.durationEstimateSec || await estimateDurationFromFile(file),
-      });
-    }
-
-    const totalSizeBytes = normalizedBatchItems.reduce((total, item) => total + Number(item.file?.size || 0), 0);
-    assertBatchLimits(normalizedBatchItems.length, totalSizeBytes);
+    assertBatchLimits(files.length, 0);
+    const normalizedItems = files.map((item, index) => normalizeBatchInputItem(item, index));
+
+    const normalizedBatchItems = [];
+    for (let index = 0; index < normalizedItems.length; index += 1) {
+      const item = normalizedItems[index];
+      if (isRemoteBatchItem(item)) {
+        normalizedBatchItems.push({
+          file: null,
+          referenceId: item.referenceId,
+          url: item.url,
+          durationEstimateSec: item.durationEstimateSec || durationEstimateSec || null,
+          hasLanguage: item.hasLanguage,
+          language: item.language,
+        });
+        continue;
+      }
+
+      const file = await normalizeFile(item.file, `file_${String(index + 1).padStart(6, "0")}.mp3`);
+      assertSupportedBatchFormat(file);
+      normalizedBatchItems.push({
+        file,
+        referenceId: item.referenceId || defaultReferenceId(index),
+        url: null,
+        durationEstimateSec: item.durationEstimateSec || await estimateDurationFromFile(file),
+        hasLanguage: item.hasLanguage,
+        language: item.language,
+      });
+    }
+
+    const totalSizeBytes = normalizedBatchItems.reduce((total, item) => total + Number(item.file?.size || 0), 0);
+    assertBatchLimits(normalizedBatchItems.length, totalSizeBytes);
     const response = await this.requestJson("/transcribe", {
       method: "POST",
       body: {
-        files: normalizedBatchItems.map((item) => (
-          item.url
-            ? {
-              reference_id: item.referenceId,
-              url: item.url,
-            }
-            : uploadDescriptorForFile(item.referenceId, item.file)
-        )),
-        ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
+        files: normalizedBatchItems.map((item) => (
+          item.url
+            ? {
+              ...(item.referenceId ? { reference_id: item.referenceId } : {}),
+              url: item.url,
+              ...(item.hasLanguage ? { language: item.language } : {}),
+            }
+            : {
+              ...uploadDescriptorForFile(item.referenceId, item.file),
+              ...(item.hasLanguage ? { language: item.language } : {}),
+            }
+        )),
+        ...(normalizedLanguage ? { language: normalizedLanguage } : {}),
+        ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
+        ...(exclude ? { exclude: Array.isArray(exclude) ? exclude.join(",") : exclude } : {}),
       },
       retryable: true,
     });
@@ -1808,9 +1616,9 @@ export class TranscribeAPI {
     return new BatchJob(this, normalizedBatchItems, response, {
       onProgress: progress,
       webhookUrl,
-      multipartConcurrency: normalizeMultipartConcurrency(multipartConcurrency ?? this.multipartConcurrency),
+      uploadConcurrency: normalizeUploadConcurrency(uploadConcurrency ?? this.uploadConcurrency),
     });
-  }
-}
-
-export default TranscribeAPI;
+  }
+}
+
+export default TranscribeAPI;