@wovin/tranz 0.0.26 → 0.1.0

package/LICENSE

@@ -630,11 +630,11 @@ state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
     <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) 2024  Manu [tennox]
+    Copyright (C) <year>  <name of author>
 
     This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Affero General Public License as published
-    by the Free Software Foundation, either version 3 of the License, or
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
 
     This program is distributed in the hope that it will be useful,

package/README.md

@@ -0,0 +1,252 @@
+# @wovin/tranz
+
+Audio transcription library with provider support and auto-splitting for long audio files.
+
+[![JSR](https://jsr.io/badges/@wovin/tranz)](https://jsr.io/@wovin/tranz)
+[![JSR Score](https://jsr.io/badges/@wovin/tranz/score)](https://jsr.io/@wovin/tranz)
+
+## Features
+
+- **Multiple Transcription Providers**: Mistral Voxtral, Whisper, GreenPT
+- **Automatic Audio Splitting**: Handles long audio files by intelligently splitting at silence points
+- **Smart Input Support**: Files, URLs (with HTTP range probing), or buffers
+- **Speaker Diarization**: Identify different speakers in audio
+- **Flexible Timestamps**: Word-level or segment-level timing
+- **Result Merging**: Automatically merge split segment results with accurate timing
+
+## Installation
+
+```sh
+# npm
+npm install @wovin/tranz
+
+# pnpm
+pnpm add @wovin/tranz
+
+# yarn
+yarn add @wovin/tranz
+
+# deno
+deno add @wovin/tranz
+
+# jsr (for any runtime)
+npx jsr add @wovin/tranz
+```
+
+## Quick Start
+
+```typescript
+import { createMistralTranscriber } from '@wovin/tranz'
+
+// Create a transcriber instance
+const transcriber = createMistralTranscriber({
+  apiKey: process.env.MISTRAL_API_KEY,
+  model: 'voxtral-mini-latest'
+})
+
+// Transcribe from file (auto-splits if too long)
+const result = await transcriber.transcribe({
+  audioPath: './interview.mp3',
+  diarize: true,
+  timestamps: 'word'
+})
+
+console.log(result.text)
+console.log(result.words) // word-level timestamps
+console.log(result.speakers) // speaker segments
+```
+
+## Usage Examples
+
+### Transcribe from URL
+
+```typescript
+// Smart handling: probes duration via HTTP, downloads only if splitting needed
+const result = await transcriber.transcribe({
+  audioUrl: 'https://example.com/audio.mp3'
+})
+
+// If you know the duration, skip detection
+const result = await transcriber.transcribe({
+  audioUrl: 'https://example.com/audio.mp3',
+  duration: 120 // seconds
+})
+```
+
+### Transcribe from Buffer
+
+```typescript
+const audioBuffer = fs.readFileSync('./audio.mp3')
+const result = await transcriber.transcribe({
+  audioBuffer,
+  mimeType: 'audio/mpeg'
+})
+```
+
+### Control Auto-Splitting
+
+```typescript
+// Disable auto-split (use for short audio)
+const result = await transcriber.transcribe({
+  audioPath: './short-clip.mp3',
+  autoSplit: false
+})
+
+// Specify custom split output directory
+const result = await transcriber.transcribe({
+  audioPath: './long-audio.mp3',
+  splitOutputDir: './segments'
+})
+```
+
+### Language Specification
+
+```typescript
+// Note: setting language disables word-level timestamps for Mistral
+const result = await transcriber.transcribe({
+  audioPath: './french-audio.mp3',
+  language: 'fr',
+  timestamps: 'segment'
+})
+```
+
+### Custom Logging
+
+```typescript
+const result = await transcriber.transcribe({
+  audioPath: './audio.mp3',
+  logger: {
+    info: (msg) => console.log(`[INFO] ${msg}`),
+    warn: (msg) => console.warn(`[WARN] ${msg}`),
+    debug: (msg) => console.debug(`[DEBUG] ${msg}`)
+  },
+  verbose: true // promotes debug logs to info level
+})
+```
+
+## Advanced: Using Providers Directly
+
+```typescript
+import { MistralProvider, WhisperProvider } from '@wovin/tranz/providers'
+
+// Mistral provider
+const mistral = new MistralProvider()
+const result = await mistral.transcribe({
+  audioPath: './audio.mp3',
+  apiKey: process.env.MISTRAL_API_KEY,
+  model: 'voxtral-mini-latest',
+  diarize: true,
+  timestampGranularity: 'word'
+})
+
+// Whisper provider (local)
+const whisper = new WhisperProvider()
+const result = await whisper.transcribe({
+  audioPath: './audio.mp3',
+  model: 'base'
+})
+```
+
+## Advanced: Audio Utilities
+
+```typescript
+import {
+  autoSplitAudio,
+  getAudioDuration,
+  mergeTranscriptionResults
+} from '@wovin/tranz/audio'
+
+// Get audio duration
+const duration = await getAudioDuration('./audio.mp3')
+
+// Split long audio at optimal silence points
+const segments = await autoSplitAudio('./long-audio.mp3', './output-dir', {
+  maxDurationSec: 300, // 5 minutes
+  minSilenceDuration: 0.5,
+  silenceThreshold: -40
+})
+
+// Manually transcribe and merge segments
+const results = await Promise.all(
+  segments.map(seg => transcribe(seg.outputPath))
+)
+const merged = mergeTranscriptionResults(results, segments)
+```
+
+## API Reference
+
+### `createMistralTranscriber(config)`
+
+Creates a Mistral transcriber instance with auto-splitting support.
+
+**Config:**
+- `apiKey: string` - Mistral API key (required)
+- `model?: string` - Model name (default: 'voxtral-mini-latest')
+
+**Returns:** `MistralTranscriber` with `transcribe(options)` method
+
+### `TranscribeOptions`
+
+Options for the `transcribe()` method:
+
+- `audioPath?: string` - Path to audio file
+- `audioBuffer?: Buffer` - Audio data as buffer
+- `mimeType?: string` - MIME type for buffer (auto-detected if omitted)
+- `audioUrl?: string` - URL to audio file (supports HTTP range probing)
+- `duration?: number` - Known duration in seconds (skips detection)
+- `language?: string` - Language code (e.g., 'en', 'fr') - disables word timestamps
+- `model?: string` - Override default model
+- `diarize?: boolean` - Enable speaker diarization (default: true)
+- `timestamps?: 'word' | 'segment'` - Timestamp granularity (default: 'word')
+- `autoSplit?: boolean` - Auto-split long audio (default: true)
+- `splitOutputDir?: string` - Directory for split segments (default: system temp)
+- `logger?: TranscribeLogger` - Custom logger
+- `verbose?: boolean` - Enable debug logging
+
+### `TranscriptionResult`
+
+Result from transcription:
+
+- `text: string` - Full transcription text
+- `duration?: number` - Audio duration in seconds
+- `language?: string` - Detected or specified language
+- `words?: WordData[]` - Word-level timestamps and confidence
+- `speakers?: SpeakerSegment[]` - Speaker diarization data
+- `error?: string` - Error message if transcription failed
+
+### `MergedTranscriptionResult`
+
+Extended result for multi-segment transcriptions:
+
+- All fields from `TranscriptionResult`
+- `totalSegments: number` - Number of segments merged
+- `segments?: TranscriptionResult[]` - Individual segment results
+
+## Providers
+
+### Mistral (Voxtral)
+
+- Models: `voxtral-mini-latest`, `voxtral-large-latest`
+- Max recommended duration: 300s (5 minutes)
+- Auto-split supported: Yes
+- Speaker diarization: Yes
+- Word timestamps: Yes (unless language specified)
+
+### Whisper (Local)
+
+- Requires local Whisper installation
+- Models: `tiny`, `base`, `small`, `medium`, `large`
+- No API key required
+
+### GreenPT
+
+- API-based transcription
+- Requires `GREENPT_API_KEY`
+
+## License
+
+AGPL-3.0-or-later
+
+## Repository
+
+[GitLab: onezoomin/ztax/tranz](https://gitlab.com/onezoomin/ztax/tranz)

package/dist/audio.d.ts

@@ -1,6 +1,6 @@
 /**
  * @wovin/tranz/audio - Audio utilities for splitting and merging
  */
-export { autoSplitAudio, analyzeSplitPoints, detectSilenceRegions, getAudioDuration, findOptimalSplitPoints, splitAudioAtPoints, DEFAULT_SPLIT_CONFIG, type SplitConfig, type SilenceRegion, type SplitPoint, type AudioSegment, type SplitAnalysis, } from './utils/audio/split.js';
-export { mergeTranscriptionResults, formatMergedText, type MergedTranscriptionResult, type WordData, } from './utils/audio/merge-results.js';
+export { autoSplitAudio, analyzeSplitPoints, detectSilenceRegions, getAudioDuration, findOptimalSplitPoints, splitAudioAtPoints, DEFAULT_SPLIT_CONFIG, type SplitConfig, type SilenceRegion, type SplitPoint, type AudioSegment, type SplitAnalysis, } from './utils/audio/split.ts';
+export { mergeTranscriptionResults, formatMergedText, type MergedTranscriptionResult, type WordData, } from './utils/audio/merge-results.ts';
 //# sourceMappingURL=audio.d.ts.map

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * @wovin/tranz - Audio transcription library
  */
-export { createProvider, MistralProvider, WhisperProvider, GreenPTProvider, VOXTRAL_LIMITS, type ProviderName, type TranscribeParams, type TranscriptionResult, type TranscriptionProvider, } from './utils/transcription/providers.js';
-export { autoSplitAudio, analyzeSplitPoints, detectSilenceRegions, getAudioDuration, findOptimalSplitPoints, splitAudioAtPoints, DEFAULT_SPLIT_CONFIG, type SplitConfig, type SilenceRegion, type SplitPoint, type AudioSegment, type SplitAnalysis, } from './utils/audio/split.js';
-export { mergeTranscriptionResults, formatMergedText, type MergedTranscriptionResult, type WordData, } from './utils/audio/merge-results.js';
-export { formatTranscriptWithPauses } from './utils/transcription/format.js';
-export { createMistralTranscriber, transcribe, type TranscribeOptions, type MistralTranscriberConfig, } from './utils/transcription/transcribe.js';
+export { createProvider, MistralProvider, WhisperProvider, GreenPTProvider, VOXTRAL_LIMITS, type ProviderName, type TranscribeParams, type TranscriptionResult, type TranscriptionProvider, } from './utils/transcription/providers.ts';
+export { autoSplitAudio, analyzeSplitPoints, detectSilenceRegions, getAudioDuration, findOptimalSplitPoints, splitAudioAtPoints, DEFAULT_SPLIT_CONFIG, type SplitConfig, type SilenceRegion, type SplitPoint, type AudioSegment, type SplitAnalysis, } from './utils/audio/split.ts';
+export { mergeTranscriptionResults, formatMergedText, type MergedTranscriptionResult, type WordData, } from './utils/audio/merge-results.ts';
+export { formatTranscriptWithPauses } from './utils/transcription/format.ts';
+export { createMistralTranscriber, transcribe, type TranscribeOptions, type MistralTranscriberConfig, type MistralTranscriber, } from './utils/transcription/transcribe.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,oCAAoC,CAAA;AAG3C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,KAAK,yBAAyB,EAC9B,KAAK,QAAQ,GACd,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAG5E,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,MAAM,qCAAqC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,oCAAoC,CAAA;AAG3C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,KAAK,yBAAyB,EAC9B,KAAK,QAAQ,GACd,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAG5E,OAAO,EACL,wBAAwB,EACxB,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,qCAAqC,CAAA"}

package/dist/index.min.js

@@ -674,15 +674,64 @@ function formatTranscriptWithPauses(transcript, words, shortPauseThreshold = 1,
 
 // src/utils/transcription/transcribe.ts
 import * as fs3 from "fs";
+import * as https from "https";
+import * as http from "http";
 import * as os from "os";
 import * as path3 from "path";
+var defaultLogger = {
+  info: (msg) => console.log(`[tranz] ${msg}`),
+  warn: (msg) => console.warn(`[tranz] ${msg}`),
+  debug: () => {
+  }
+  // silent by default
+};
+async function downloadToTempFile(url, outputDir) {
+  const tempPath = path3.join(outputDir, `download-${Date.now()}.audio`);
+  const file = fs3.createWriteStream(tempPath);
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith("https") ? https : http;
+    protocol.get(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302) {
+        const redirectUrl = response.headers.location;
+        if (redirectUrl) {
+          file.close();
+          fs3.unlinkSync(tempPath);
+          downloadToTempFile(redirectUrl, outputDir).then(resolve).catch(reject);
+          return;
+        }
+      }
+      if (response.statusCode !== 200) {
+        reject(new Error(`Failed to download: HTTP ${response.statusCode}`));
+        return;
+      }
+      response.pipe(file);
+      file.on("finish", () => {
+        file.close();
+        resolve(tempPath);
+      });
+    }).on("error", (err) => {
+      fs3.unlink(tempPath, () => {
+      });
+      reject(err);
+    });
+  });
+}
+async function tryGetUrlDuration(url) {
+  try {
+    return await getAudioDuration(url);
+  } catch {
+    return void 0;
+  }
+}
 function createMistralTranscriber(config) {
   const provider = new MistralProvider();
   const defaultModel = config.model || "voxtral-mini-latest";
   return {
     /**
-     * Transcribe audio with auto-splitting for long files (file path only)
-     * Diarization and word timestamps enabled by default
+     * Transcribe audio with smart auto-splitting
+     * - For files: checks duration and splits if needed
+     * - For URLs: probes duration via HTTP range request, downloads only if splitting needed
+     * - For buffers: transcribes directly (no splitting)
      */
     async transcribe(options) {
       const {
@@ -690,16 +739,22 @@ function createMistralTranscriber(config) {
         audioBuffer,
         mimeType,
         audioUrl,
+        duration: knownDuration,
         language,
         model = defaultModel,
         diarize = true,
         timestamps = language ? void 0 : "word",
-        autoSplit = true,
-        splitOutputDir
+        autoSplit,
+        splitOutputDir,
+        logger: customLogger,
+        verbose
       } = options;
-      if (audioUrl || audioBuffer) {
+      const log = customLogger || defaultLogger;
+      if (verbose) log.debug = log.info;
+      const maxDuration = VOXTRAL_LIMITS.recommendedMaxDurationSec;
+      if (audioBuffer) {
+        log.info(`Transcribing from buffer (${(audioBuffer.length / 1024 / 1024).toFixed(2)} MB)`);
         const result = await provider.transcribe({
-          audioUrl,
           audioBuffer,
           mimeType,
           apiKey: config.apiKey,
@@ -710,12 +765,74 @@ function createMistralTranscriber(config) {
         });
         return { ...result, totalSegments: 1 };
       }
+      if (audioUrl) {
+        if (autoSplit === false) {
+          log.info(`Transcribing URL directly (autoSplit disabled)`);
+          const result2 = await provider.transcribe({
+            audioUrl,
+            apiKey: config.apiKey,
+            model,
+            language,
+            diarize,
+            timestampGranularity: timestamps
+          });
+          return { ...result2, totalSegments: 1 };
+        }
+        let duration2 = knownDuration;
+        if (duration2 === void 0) {
+          log.info(`Probing URL duration via ffprobe...`);
+          duration2 = await tryGetUrlDuration(audioUrl);
+          if (duration2 !== void 0) {
+            log.info(`Duration detected: ${duration2.toFixed(1)}s`);
+          } else {
+            log.warn(`Duration detection failed, will download to check`);
+          }
+        } else {
+          log.debug(`Using provided duration: ${duration2.toFixed(1)}s`);
+        }
+        if (duration2 !== void 0 && duration2 <= maxDuration) {
+          log.info(`Duration ${duration2.toFixed(1)}s <= ${maxDuration}s, using URL directly`);
+          const result2 = await provider.transcribe({
+            audioUrl,
+            apiKey: config.apiKey,
+            model,
+            language,
+            diarize,
+            timestampGranularity: timestamps
+          });
+          return { ...result2, totalSegments: 1 };
+        }
+        log.info(`Downloading URL to temp file for processing...`);
+        const outDir2 = splitOutputDir || path3.join(os.tmpdir(), `tranz-${Date.now()}`);
+        fs3.mkdirSync(outDir2, { recursive: true });
+        const tempFile = await downloadToTempFile(audioUrl, outDir2);
+        log.info(`Downloaded to ${tempFile}`);
+        const result = await this.transcribe({
+          audioPath: tempFile,
+          language,
+          model,
+          diarize,
+          timestamps,
+          autoSplit: true,
+          splitOutputDir: outDir2,
+          logger: customLogger,
+          verbose
+        });
+        try {
+          fs3.unlinkSync(tempFile);
+        } catch {
+        }
+        return result;
+      }
       if (!audioPath) {
         return { text: "", error: "No audio input provided (audioPath, audioBuffer, or audioUrl required)" };
       }
-      const duration = await getAudioDuration(audioPath);
-      const needsSplit = autoSplit && duration > VOXTRAL_LIMITS.recommendedMaxDurationSec;
+      log.debug(`Processing file: ${audioPath}`);
+      const duration = knownDuration ?? await getAudioDuration(audioPath);
+      log.info(`Audio duration: ${duration.toFixed(1)}s`);
+      const needsSplit = autoSplit !== false && duration > maxDuration;
       if (!needsSplit) {
+        log.info(`Transcribing file directly (no split needed)`);
         const result = await provider.transcribe({
           audioPath,
           apiKey: config.apiKey,
@@ -726,13 +843,17 @@ function createMistralTranscriber(config) {
         });
         return { ...result, totalSegments: 1 };
       }
+      log.info(`Duration ${duration.toFixed(1)}s > ${maxDuration}s, splitting audio...`);
       const outDir = splitOutputDir || path3.join(os.tmpdir(), `tranz-split-${Date.now()}`);
       fs3.mkdirSync(outDir, { recursive: true });
       const segments = await autoSplitAudio(audioPath, outDir, {
-        maxDurationSec: VOXTRAL_LIMITS.recommendedMaxDurationSec
+        maxDurationSec: maxDuration
       });
+      log.info(`Split into ${segments.length} segments`);
       const results = [];
-      for (const segment of segments) {
+      for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        log.info(`Transcribing segment ${i + 1}/${segments.length} (${segment.durationSec.toFixed(1)}s)`);
         const result = await provider.transcribe({
           audioPath: segment.outputPath,
           apiKey: config.apiKey,
@@ -743,6 +864,7 @@ function createMistralTranscriber(config) {
         });
         results.push(result);
       }
+      log.info(`Merging ${segments.length} segments`);
       return mergeTranscriptionResults(results, segments);
     }
   };

package/dist/providers.d.ts

@@ -1,6 +1,6 @@
 /**
  * @wovin/tranz/providers - Transcription provider implementations
  */
-export { createProvider, MistralProvider, WhisperProvider, GreenPTProvider, VOXTRAL_LIMITS, type ProviderName, type TranscribeParams, type TranscriptionResult, type TranscriptionProvider, } from './utils/transcription/providers.js';
-export { createMistralTranscriber, transcribe, type TranscribeOptions, type MistralTranscriberConfig, } from './utils/transcription/transcribe.js';
+export { createProvider, MistralProvider, WhisperProvider, GreenPTProvider, VOXTRAL_LIMITS, type ProviderName, type TranscribeParams, type TranscriptionResult, type TranscriptionProvider, } from './utils/transcription/providers.ts';
+export { createMistralTranscriber, transcribe, type TranscribeOptions, type MistralTranscriberConfig, } from './utils/transcription/transcribe.ts';
 //# sourceMappingURL=providers.d.ts.map

package/dist/providers.min.js

@@ -347,6 +347,8 @@ var GreenPTProvider = class {
 
 // src/utils/transcription/transcribe.ts
 import * as fs3 from "fs";
+import * as https from "https";
+import * as http from "http";
 import * as os from "os";
 import * as path3 from "path";
 
@@ -598,13 +600,60 @@ function mergeTranscriptionResults(results, segments) {
 }
 
 // src/utils/transcription/transcribe.ts
+var defaultLogger = {
+  info: (msg) => console.log(`[tranz] ${msg}`),
+  warn: (msg) => console.warn(`[tranz] ${msg}`),
+  debug: () => {
+  }
+  // silent by default
+};
+async function downloadToTempFile(url, outputDir) {
+  const tempPath = path3.join(outputDir, `download-${Date.now()}.audio`);
+  const file = fs3.createWriteStream(tempPath);
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith("https") ? https : http;
+    protocol.get(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302) {
+        const redirectUrl = response.headers.location;
+        if (redirectUrl) {
+          file.close();
+          fs3.unlinkSync(tempPath);
+          downloadToTempFile(redirectUrl, outputDir).then(resolve).catch(reject);
+          return;
+        }
+      }
+      if (response.statusCode !== 200) {
+        reject(new Error(`Failed to download: HTTP ${response.statusCode}`));
+        return;
+      }
+      response.pipe(file);
+      file.on("finish", () => {
+        file.close();
+        resolve(tempPath);
+      });
+    }).on("error", (err) => {
+      fs3.unlink(tempPath, () => {
+      });
+      reject(err);
+    });
+  });
+}
+async function tryGetUrlDuration(url) {
+  try {
+    return await getAudioDuration(url);
+  } catch {
+    return void 0;
+  }
+}
 function createMistralTranscriber(config) {
   const provider = new MistralProvider();
   const defaultModel = config.model || "voxtral-mini-latest";
   return {
     /**
-     * Transcribe audio with auto-splitting for long files (file path only)
-     * Diarization and word timestamps enabled by default
+     * Transcribe audio with smart auto-splitting
+     * - For files: checks duration and splits if needed
+     * - For URLs: probes duration via HTTP range request, downloads only if splitting needed
+     * - For buffers: transcribes directly (no splitting)
      */
     async transcribe(options) {
       const {
@@ -612,16 +661,22 @@ function createMistralTranscriber(config) {
         audioBuffer,
         mimeType,
         audioUrl,
+        duration: knownDuration,
         language,
         model = defaultModel,
         diarize = true,
         timestamps = language ? void 0 : "word",
-        autoSplit = true,
-        splitOutputDir
+        autoSplit,
+        splitOutputDir,
+        logger: customLogger,
+        verbose
       } = options;
-      if (audioUrl || audioBuffer) {
+      const log = customLogger || defaultLogger;
+      if (verbose) log.debug = log.info;
+      const maxDuration = VOXTRAL_LIMITS.recommendedMaxDurationSec;
+      if (audioBuffer) {
+        log.info(`Transcribing from buffer (${(audioBuffer.length / 1024 / 1024).toFixed(2)} MB)`);
         const result = await provider.transcribe({
-          audioUrl,
           audioBuffer,
           mimeType,
           apiKey: config.apiKey,
@@ -632,12 +687,74 @@ function createMistralTranscriber(config) {
         });
         return { ...result, totalSegments: 1 };
       }
+      if (audioUrl) {
+        if (autoSplit === false) {
+          log.info(`Transcribing URL directly (autoSplit disabled)`);
+          const result2 = await provider.transcribe({
+            audioUrl,
+            apiKey: config.apiKey,
+            model,
+            language,
+            diarize,
+            timestampGranularity: timestamps
+          });
+          return { ...result2, totalSegments: 1 };
+        }
+        let duration2 = knownDuration;
+        if (duration2 === void 0) {
+          log.info(`Probing URL duration via ffprobe...`);
+          duration2 = await tryGetUrlDuration(audioUrl);
+          if (duration2 !== void 0) {
+            log.info(`Duration detected: ${duration2.toFixed(1)}s`);
+          } else {
+            log.warn(`Duration detection failed, will download to check`);
+          }
+        } else {
+          log.debug(`Using provided duration: ${duration2.toFixed(1)}s`);
+        }
+        if (duration2 !== void 0 && duration2 <= maxDuration) {
+          log.info(`Duration ${duration2.toFixed(1)}s <= ${maxDuration}s, using URL directly`);
+          const result2 = await provider.transcribe({
+            audioUrl,
+            apiKey: config.apiKey,
+            model,
+            language,
+            diarize,
+            timestampGranularity: timestamps
+          });
+          return { ...result2, totalSegments: 1 };
+        }
+        log.info(`Downloading URL to temp file for processing...`);
+        const outDir2 = splitOutputDir || path3.join(os.tmpdir(), `tranz-${Date.now()}`);
+        fs3.mkdirSync(outDir2, { recursive: true });
+        const tempFile = await downloadToTempFile(audioUrl, outDir2);
+        log.info(`Downloaded to ${tempFile}`);
+        const result = await this.transcribe({
+          audioPath: tempFile,
+          language,
+          model,
+          diarize,
+          timestamps,
+          autoSplit: true,
+          splitOutputDir: outDir2,
+          logger: customLogger,
+          verbose
+        });
+        try {
+          fs3.unlinkSync(tempFile);
+        } catch {
+        }
+        return result;
+      }
       if (!audioPath) {
         return { text: "", error: "No audio input provided (audioPath, audioBuffer, or audioUrl required)" };
       }
-      const duration = await getAudioDuration(audioPath);
-      const needsSplit = autoSplit && duration > VOXTRAL_LIMITS.recommendedMaxDurationSec;
+      log.debug(`Processing file: ${audioPath}`);
+      const duration = knownDuration ?? await getAudioDuration(audioPath);
+      log.info(`Audio duration: ${duration.toFixed(1)}s`);
+      const needsSplit = autoSplit !== false && duration > maxDuration;
       if (!needsSplit) {
+        log.info(`Transcribing file directly (no split needed)`);
         const result = await provider.transcribe({
           audioPath,
           apiKey: config.apiKey,
@@ -648,13 +765,17 @@ function createMistralTranscriber(config) {
         });
         return { ...result, totalSegments: 1 };
       }
+      log.info(`Duration ${duration.toFixed(1)}s > ${maxDuration}s, splitting audio...`);
       const outDir = splitOutputDir || path3.join(os.tmpdir(), `tranz-split-${Date.now()}`);
       fs3.mkdirSync(outDir, { recursive: true });
       const segments = await autoSplitAudio(audioPath, outDir, {
-        maxDurationSec: VOXTRAL_LIMITS.recommendedMaxDurationSec
+        maxDurationSec: maxDuration
       });
+      log.info(`Split into ${segments.length} segments`);
       const results = [];
-      for (const segment of segments) {
+      for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        log.info(`Transcribing segment ${i + 1}/${segments.length} (${segment.durationSec.toFixed(1)}s)`);
         const result = await provider.transcribe({
           audioPath: segment.outputPath,
           apiKey: config.apiKey,
@@ -665,6 +786,7 @@ function createMistralTranscriber(config) {
         });
         results.push(result);
       }
+      log.info(`Merging ${segments.length} segments`);
       return mergeTranscriptionResults(results, segments);
     }
   };

package/dist/utils/audio/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Audio utilities for tranz-cli
  */
-export * from './split.js';
-export * from './merge-results.js';
+export * from './split.ts';
+export * from './merge-results.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/audio/merge-results.d.ts

@@ -1,8 +1,8 @@
 /**
  * Utilities for merging transcription results from split audio segments
  */
-import type { TranscriptionResult } from '../transcription/providers.js';
-import type { AudioSegment } from './split.js';
+import type { TranscriptionResult } from '../transcription/providers.ts';
+import type { AudioSegment } from './split.ts';
 /**
  * Word-level data with timing information
  */

package/dist/utils/file-utils.d.ts

@@ -1,4 +1,4 @@
-import path from 'path';
+import path from 'node:path';
 export declare const getExt: (filePath: string) => string;
 export declare const getName: (filePath: string) => string;
 export declare const getNameWithExt: (filePath: string) => string;

package/dist/utils/file-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAA;AAEvB,eAAO,MAAM,MAAM,GAAI,UAAU,MAAM,WAEtC,CAAA;AACD,eAAO,MAAM,OAAO,GAAI,UAAU,MAAM,WAEvC,CAAA;AACD,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,WAG9C,CAAA;AACD,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,oBAG3C,CAAA"}
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,eAAO,MAAM,MAAM,GAAI,UAAU,MAAM,WAEtC,CAAA;AACD,eAAO,MAAM,OAAO,GAAI,UAAU,MAAM,WAEvC,CAAA;AACD,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,WAG9C,CAAA;AACD,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,oBAG3C,CAAA"}

package/dist/utils/transcription/transcribe.d.ts

@@ -1,7 +1,13 @@
 /**
  * Simple high-level transcription API with good defaults
  */
-import { type MergedTranscriptionResult } from '../audio/merge-results.js';
+import { type MergedTranscriptionResult } from '../audio/merge-results.ts';
+/** Logger interface for transcription progress */
+export interface TranscribeLogger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    debug: (msg: string) => void;
+}
 export interface TranscribeOptions {
     /** Path to audio file */
     audioPath?: string;
@@ -11,6 +17,8 @@ export interface TranscribeOptions {
     mimeType?: string;
     /** URL to audio file (e.g., IPFS gateway URL) */
     audioUrl?: string;
+    /** Known duration in seconds (skips duration detection for URL input) */
+    duration?: number;
     /** Language code (e.g. 'en', 'fr') - note: disables word timestamps for Mistral */
     language?: string;
     /** Model to use (default: voxtral-mini-latest) */
@@ -19,10 +27,14 @@ export interface TranscribeOptions {
     diarize?: boolean;
     /** Timestamp granularity: 'word' | 'segment' (default: 'word', disabled if language set) */
     timestamps?: 'word' | 'segment';
-    /** Auto-split long audio (default: true, only works with audioPath) */
+    /** Auto-split long audio (default: true). For URLs, detects duration first. */
     autoSplit?: boolean;
     /** Output directory for split segments (default: system temp) */
     splitOutputDir?: string;
+    /** Custom logger (default: console) */
+    logger?: TranscribeLogger;
+    /** Enable verbose/debug logging */
+    verbose?: boolean;
 }
 export interface MistralTranscriberConfig {
     /** Mistral API key */
@@ -40,20 +52,21 @@ export interface MistralTranscriberConfig {
  * // From file (supports auto-split for long audio)
  * const result = await transcriber.transcribe({ audioPath: './interview.mp3' })
  *
- * // From URL (e.g., IPFS gateway)
+ * // From URL (auto-detects if splitting needed, downloads only if necessary)
  * const result = await transcriber.transcribe({ audioUrl: 'https://gateway.ipfs.io/ipfs/Qm...' })
  *
+ * // From URL with known duration (skips detection)
+ * const result = await transcriber.transcribe({ audioUrl: '...', duration: 120 })
+ *
  * // From buffer
  * const result = await transcriber.transcribe({ audioBuffer: buffer, mimeType: 'audio/mpeg' })
  * ```
  */
-export declare function createMistralTranscriber(config: MistralTranscriberConfig): {
-    /**
-     * Transcribe audio with auto-splitting for long files (file path only)
-     * Diarization and word timestamps enabled by default
-     */
+/** Transcriber interface returned by createMistralTranscriber */
+export interface MistralTranscriber {
     transcribe(options: TranscribeOptions): Promise<MergedTranscriptionResult>;
-};
+}
+export declare function createMistralTranscriber(config: MistralTranscriberConfig): MistralTranscriber;
 /** Alias for simpler import */
 export declare const transcribe: typeof createMistralTranscriber;
 //# sourceMappingURL=transcribe.d.ts.map

package/dist/utils/transcription/transcribe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../../../src/utils/transcription/transcribe.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AAErG,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB;IAKrE;;;OAGG;wBACuB,iBAAiB,GAAG,OAAO,CAAC,yBAAyB,CAAC;EA4EnF;AAED,+BAA+B;AAC/B,eAAO,MAAM,UAAU,iCAA2B,CAAA"}
+{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../../../src/utils/transcription/transcribe.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AAErG,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7B;AAQD,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,uCAAuC;IACvC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IACzB,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAkDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAA;CAC3E;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,kBAAkB,CA4K7F;AAED,+BAA+B;AAC/B,eAAO,MAAM,UAAU,iCAA2B,CAAA"}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@wovin/tranz",
-  "version": "0.0.26",
+  "version": "0.1.0",
   "type": "module",
   "description": "Audio transcription library with provider support and auto-splitting",
   "author": "gotjoshua @gotjoshua",
-  "license": "ISC",
+  "license": "AGPL-3.0-or-later",
   "homepage": "https://gitlab.com/onezoomin/ztax/tranz",
-  "repository": "https://gitlab.com/onezoomin/ztax/tranz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/wovin/wovin.git",
+    "directory": "packages/@wovin/tranz"
+  },
   "bugs": "https://gitlab.com/onezoomin/ztax/tranz/-/issues",
   "main": "./dist/index.min.js",
   "module": "./dist/index.min.js",
@@ -56,7 +60,6 @@
     "dev": "concurrently \"pnpm dev:code\" \"pnpm dev:types\"",
     "dev:code": "tsup --watch",
     "dev:types": "tsc --emitDeclarationOnly --declaration --watch",
-    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
-    "pub": "npm publish --tag latest --access=public"
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist"
   }
 }