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

> Learn to specify a custom output file path for transcriptions in insanely-fast-whisper using the --transcript-path argument. Control where your transcription results are saved with ease.

- Repository: [vb/insanely-fast-whisper](https://github.com/Vaibhavs10/insanely-fast-whisper)
- Tags: how-to-guide
- Published: 2026-03-27

---

**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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/src/insanely_fast_whisper/cli.py)**. The argument parser registers this optional flag with a string type and a default value:

```python
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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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:

```python
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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/output.json) in the current directory:

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

```

### Relative Custom Paths

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

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/output.json).
- The argument is defined in **[`src/insanely_fast_whisper/cli.py`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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`](https://github.com/Vaibhavs10/insanely-fast-whisper/blob/main/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.