Function signature async function transcribe ( content : string | ReadStream , options ?: TranscribeOptions ) : Promise < Segment []>
Transcribes audio content and returns an array of transcript segments with timestamps. This function handles preprocessing the audio, splitting it into chunks, and transcribing each chunk using Wit.ai’s API.
Parameters content
string | ReadStream
required
The audio content to transcribe. Can be:
A file path (e.g., 'path/to/audio.mp3')
A URL to a remote audio file
A Node.js ReadStream object
Configuration options for transcription Maximum number of concurrent transcription operations. Limited by the number of available API keys provided to init() Number of retry attempts for failed transcription requests. Uses exponential backoff between retries.
If true, temporary processing directories and audio chunks won’t be deleted after transcription. Useful for debugging or when you need to retry failed transcriptions with resumeFailedTranscriptions() Options for splitting audio into chunks. Target duration for each audio chunk in seconds. Must be between 4 and 300 seconds. Wit.ai has a maximum file duration limit, so large files are automatically split.
Configure silence detection for smarter chunk splitting. Volume threshold in dB for detecting silence. More negative values detect quieter silence.
Callbacks for monitoring and responding to various stages of the transcription process. onTranscriptionStarted
(totalChunks: number) => Promise<void>
Called before transcription begins, with the total number of chunks to be processed.
onTranscriptionProgress
(chunkIndex: number) => void
Called when each individual chunk is transcribed, with the index of the completed chunk.
onTranscriptionFinished
(transcripts: Segment[]) => Promise<void>
Called when all transcription is complete, with the array of all transcribed segments.
Returns A promise that resolves to an array of transcript segments. Each segment contains: The transcribed text for this segment.
Start time of the segment in seconds.
End time of the segment in seconds.
Confidence score for this transcription (between 0 and 1). Higher values indicate greater confidence.
Optional word-by-word breakdown of the transcription with individual timings. Each token contains:
text: The word or phrasestart: Start time in secondsend: End time in secondsconfidence: Confidence score (0-1) Throws Thrown when one or more chunks fail to transcribe. The error object contains:
failures: Array of failed transcription attempts with error detailstranscripts: Successfully transcribed segmentsoutputDir: Path to the temporary directory containing audio chunkschunkFiles: Array of all audio chunk files You can use resumeFailedTranscriptions() Thrown if options validation fails (e.g., invalid chunkDuration values).
Examples Basic transcription import { init , transcribe } from 'tafrigh' ; init ({ apiKeys: [ 'your-wit-ai-key' ] }); const transcript = await transcribe ( 'path/to/audio.mp3' ); console . log ( transcript ); // [ // { text: "Hello world", start: 0, end: 2.5, confidence: 0.98 }, // { text: "This is a test", start: 2.5, end: 5.0, confidence: 0.95 } // ]
Concurrent transcription with multiple API keys import { init , transcribe } from 'tafrigh' ; init ({ apiKeys: [ 'key-1' , 'key-2' , 'key-3' ] }); const transcript = await transcribe ( 'large-audio-file.mp3' , { concurrency: 3 , splitOptions: { chunkDuration: 60 } });
Custom chunk duration and silence detection const transcript = await transcribe ( 'podcast.mp3' , { splitOptions: { chunkDuration: 120 , silenceDetection: { silenceThreshold: - 35 } } });
Progress tracking with callbacks let totalChunks = 0 ; let processedChunks = 0 ; const transcript = await transcribe ( 'audio.mp3' , { callbacks: { onTranscriptionStarted : async ( total ) => { totalChunks = total ; console . log ( `Starting transcription of ${ total } chunks` ); }, onTranscriptionProgress : ( index ) => { processedChunks ++ ; console . log ( `Progress: ${ processedChunks } / ${ totalChunks } chunks` ); }, onTranscriptionFinished : async ( transcripts ) => { console . log ( `Completed! Total segments: ${ transcripts . length } ` ); } } });
Error handling and retry import { init , transcribe , resumeFailedTranscriptions , TranscriptionError } from 'tafrigh' ; init ({ apiKeys: [ 'your-wit-ai-key' ] }); try { const transcript = await transcribe ( 'audio.mp3' , { preventCleanup: true // Keep chunks for potential retry }); console . log ( 'Success:' , transcript ); } catch ( error ) { if ( error instanceof TranscriptionError ) { console . log ( `Failed chunks: ${ error . failures . length } ` ); console . log ( `Successful chunks: ${ error . transcripts . length } ` ); // Retry failed chunks const result = await resumeFailedTranscriptions ( error , { concurrency: 1 }); if ( result . failures . length === 0 ) { console . log ( 'All chunks transcribed successfully!' ); console . log ( result . transcripts ); } } else { throw error ; } }
Transcribing from a stream import { createReadStream } from 'fs' ; import { transcribe } from 'tafrigh' ; const stream = createReadStream ( 'audio.mp3' ); const transcript = await transcribe ( stream );
Transcribing from a URL const transcript = await transcribe ( 'https://example.com/audio.mp3' );
The transcribe() function automatically cleans up temporary files after completion. Set preventCleanup: true if you need to preserve chunks for debugging or retry operations.
Wit.ai has rate limits and file size restrictions. Use multiple API keys with higher concurrency to improve throughput for large files.