How to Specify a Custom Output File Path for Transcriptions in insanely-fast-whisper

Use the --transcript-path argument when invoking the insanely-fast-whisper CLI to write transcription results to any valid file system path.

The insanely-fast-whisper tool provides a flexible command-line interface for audio transcription built on standard Python argparse. By default, the CLI writes results to output.json in the current working directory, but you can redirect this output to custom locations using a dedicated flag. This guide walks through the implementation details in the Vaibhavs10/insanely-fast-whisper repository and provides practical examples for controlling where your transcription files are saved.

The --transcript-path Argument

The output destination is controlled by the --transcript-path parameter defined in src/insanely_fast_whisper/cli.py. The argument parser registers this optional flag with a string type and a default value:

parser.add_argument(
    "--transcript-path",
    required=False,
    default="output.json",
    type=str,
    help="Path to save the transcription output. (default: output.json)",
)

When you invoke the CLI without this flag, the tool automatically uses output.json as the destination. Supplying any relative or absolute path overwrites this default, directing the JSON output to your specified location.

How the Output File is Written

After the Whisper pipeline processes the audio, the CLI writes results using Python’s built-in open function with the user-provided path. The workflow in src/insanely_fast_whisper/cli.py follows this sequence:

1. Result construction: The build_result function (imported from src/insanely_fast_whisper/utils/result.py) assembles a dictionary containing transcription chunks, concatenated text, and optional speaker labels from diarization.
2. File serialization: The code opens the file handle using args.transcript_path and writes formatted JSON:

with open(args.transcript_path, "w", encoding="utf8") as fp:
    result = build_result([], outputs)          # includes diarization data if enabled

    json.dump(result, fp, ensure_ascii=False)

Because the implementation uses standard Python file I/O, any path accepted by open()—including relative paths, absolute paths, or paths across different drives—works as the --transcript-path value.

Practical Usage Examples

Default Output Behavior

Running the tool without the flag creates output.json in the current directory:

python -m insanely_fast_whisper.cli \
    --file-name audio.wav

Relative Custom Paths

Save results to a subdirectory or different filename using relative notation:

python -m insanely_fast_whisper.cli \
    --file-name audio.wav \
    --transcript-path results/my_transcript.json

Absolute Paths (Linux/macOS)

Specify full system paths to place files outside the working directory:

python -m insanely_fast_whisper.cli \
    --file-name audio.wav \
    --transcript-path /home/user/transcriptions/audio_result.json

Custom File Extensions

While the output format is always JSON, you can use any file extension. The content structure remains unchanged:

python -m insanely_fast_whisper.cli \
    --file-name audio.wav \
    --transcript-path /tmp/audio_output.txt

Combining with Speaker Diarization

When using the --hf-token flag for speaker diarization, use the same output path argument. The resulting JSON will include speaker segments alongside transcription data:

python -m insanely_fast_whisper.cli \
    --file-name audio.wav \
    --hf-token hf_xxxYOURTOKENxxx \
    --transcript-path diarized_output.json

Implementation Architecture

Understanding the data flow helps debug path-related issues:

1. Argument parsing: argparse captures --transcript-path in src/insanely_fast_whisper/cli.py.
2. Pipeline execution: The Whisper model generates transcription chunks stored in outputs.
3. Optional diarization: If a Hugging Face token is provided, speaker segmentation data is appended.
4. Result assembly: build_result in src/insanely_fast_whisper/utils/result.py creates the final JsonTranscriptionResult dictionary.
5. File persistence: Python’s open(args.transcript_path, "w") writes the JSON to disk.

All path handling relies on standard Python file operations, meaning the tool inherits Python’s cross-platform path support and error handling (e.g., raising FileNotFoundError if parent directories do not exist).

Summary

• The --transcript-path argument controls where transcription JSON is saved, defaulting to output.json.
• The argument is defined in src/insanely_fast_whisper/cli.py and accepts any valid file system path string.
• Output writing occurs via Python’s built-in open() and json.dump() functions, supporting both relative and absolute paths.
• The build_result function in src/insanely_fast_whisper/utils/result.py constructs the JSON payload before serialization.
• File extensions do not affect the JSON content format; the tool always writes structured transcription data.

Frequently Asked Questions

What is the default output file path if I don't specify --transcript-path?

The CLI defaults to output.json in the current working directory where the command is executed. This is hardcoded as the default value in the argument parser definition in src/insanely_fast_whisper/cli.py.

Can I save the transcription as a .txt file instead of .json?

Yes, you can specify any file extension (e.g., .txt, .log, .data), but the content format remains JSON regardless of the extension. The tool uses json.dump() to serialize the build_result dictionary, so the file will always contain structured JSON data even with a .txt extension.

Does enabling speaker diarization change how I specify the output path?

No, the --transcript-path flag works identically whether diarization is enabled or not. When you provide a Hugging Face token via --hf-token, the build_result function simply adds speaker segmentation data to the JSON structure before it is written to your specified path.

What happens if the directory in my custom path doesn't exist?

The tool will raise a FileNotFoundError because the Python open() function does not automatically create parent directories. You must ensure the target directory exists before running the command, or use external tools (like mkdir -p) to create the directory structure beforehand.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}