Skip to main content

​
Overview

Tafrigh provides specialized error types that give you detailed information about transcription failures, including which chunks failed, which succeeded, and access to temporary files for debugging.

​
TranscriptionError

Thrown when one or more audio chunks fail to transcribe. This error includes information about both successful and failed transcriptions, allowing you to resume from failures or extract partial results.

​
Type definition

class TranscriptionError extends Error {
    readonly chunkFiles: AudioChunk[];
    readonly failures: FailedTranscription[];
    readonly outputDir?: string;
    readonly transcripts: Segment[];
    
    get failedChunks(): AudioChunk[];
    get hasFailures(): boolean;
}

​
Properties

​
message
string
required
Error message describing the failure.Typically includes the number of failed chunks.
​
name
string
required
Always set to 'TranscriptionError' for type identification.
​
chunkFiles
AudioChunk[]
required
All audio chunks that were generated from the original file.
​
failures
FailedTranscription[]
required
Array of failed transcription attempts with error details.See FailedTranscription below for structure.
​
outputDir
string
Path to the temporary directory containing chunk files.
Only available when preventCleanup: true is set in options. Otherwise, the directory is automatically cleaned up before the error is thrown.
​
transcripts
Segment[]
required
Successfully transcribed segments.You can use these partial results or pass them to resumeFailedTranscriptions() to retry only the failed chunks.

​
Computed properties

​
failedChunks
AudioChunk[]
Convenience getter that extracts just the chunk objects from the failures array.Equivalent to error.failures.map(f => f.chunk).
​
hasFailures
boolean
Returns true if there are any failures.Equivalent to error.failures.length > 0.

​
FailedTranscription

Represents a single failed transcription attempt, including the chunk that failed and the error that occurred.

​
Type definition

type FailedTranscription = {
    chunk: AudioChunk;
    error: unknown;
    index: number;
};

​
Properties

​
chunk
AudioChunk
required
The audio chunk that failed to transcribe.Contains filename and range properties.
​
error
unknown
required
The error that occurred during transcription.This could be a network error, API error, or any other exception thrown during the transcription process.
​
index
number
required
The 0-based index of this chunk in the original chunk array.Useful for tracking which specific chunks failed in order.

​
Usage examples

import { transcribe, TranscriptionError } from 'tafrigh';

try {
  const transcript = await transcribe('audio.mp3');
  console.log('Success!', transcript);
} catch (error) {
  if (error instanceof TranscriptionError) {
    console.error(`Failed to transcribe ${error.failures.length} chunks`);
    console.log(`Got ${error.transcripts.length} successful segments`);
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Error message format

The error message follows this pattern: 
Failed to transcribe N chunk(s)
Where N is the number of chunks that failed transcription.

​
When errors are thrown

TranscriptionError is thrown when:
  1. One or more audio chunks fail to transcribe after all retry attempts
  2. The Wit.ai API returns an error response
  3. Network errors occur during API calls
  4. Invalid audio format prevents transcription
Even if only one chunk out of many fails, a TranscriptionError will be thrown. However, you can access all successfully transcribed segments via the transcripts property.

​
Best practices

Always check for partial results

Even when transcription fails, you may have successfully transcribed most of the audio. Always check error.transcripts.

Use resumeFailedTranscriptions

Instead of reprocessing the entire file, retry only the failed chunks using resumeFailedTranscriptions().

Enable preventCleanup for debugging

Set preventCleanup: true to inspect the audio chunks that failed transcription.

Configure retries

Set the retries option to automatically retry failed chunks before throwing an error.

Resume failed transcriptions

Retry only the failed chunks

Error handling guide

Complete error handling strategies

TranscribeOptions

Configuration including retries and preventCleanup

Segment type

Structure of transcripts array

Build docs developers (and LLMs) love

Get started for freeTalk to us