Skip to content

hypline transcribe

Transcribe stimulus audio into word-level transcripts using a Whisper speech-recognition model. For each word in each transcript, this step records the time the word was spoken — the timing that later feeds featuregen.

hypline transcribe <dataset-root> --audio-ext <ext> [OPTIONS]

FFmpeg required

Audio is decoded through FFmpeg, which must be on your PATH. Any FFmpeg-supported format works (WAV, MP3, M4A, FLAC, video containers, …) — pass its extension to --audio-ext.

Inputs

Stimulus audio files under the stimuli/ area, with the _audio suffix:

<dataset-root>/stimuli/dyad-040/ses-1/audio/
└── dyad-040_ses-1_task-conv_run-1_audio.wav

See Hypline dataset layout for how files are named and discovered.

Extra entities in audio filenames

Audio filename entities carry into transcript and feature filenames. Any entity beyond identity and the segment entity (for example, block in ..._block-1_trial-3_audio.wav) must be recorded in events.json, or transcribe stops with an error that names the file; see Extra entities in filenames.

Options

Option Description Default
--audio-ext Extension of the audio files, e.g. .wav — required —
--model Whisper model: tiny, base, small, medium, large-v2, large-v3 large-v2
--model-dir Where to find/download model weights ~/.cache/hypline/whisperx
--device Hardware target: cpu or cuda cpu
--dyad-ids Comma-separated dyad IDs to process; omit for all all
--data-filters Narrow to specific runs/conditions — see Filter to specific runs or conditions none
--force Overwrite existing transcripts (default skips them) off

Model size vs. speed

Larger models are more accurate but slower. On a GPU, pass --device cuda. The first run downloads the chosen model to --model-dir (default ~/.cache/hypline/whisperx); later runs reuse it.

Relocating the cache

The ~/.cache/hypline root is shared by every command that downloads model weights (transcribe, featuregen semantic, featuregen spectral). Set HYPLINE_CACHE to move that root — e.g. HYPLINE_CACHE=/scratch/$USER/hypline on a cluster with a small home quota. An explicit --model-dir still wins over both.

Example

Transcribe every dyad's WAV audio with the default model:

hypline transcribe data/ --audio-ext .wav

Transcribe only dyad 040 on a GPU (pass more as a comma-separated list):

hypline transcribe data/ --audio-ext .wav --dyad-ids 040 --device cuda

Outputs

A word-level transcript per audio file, with the _transcript suffix, written beside the audio under stimuli/:

<dataset-root>/stimuli/dyad-040/ses-1/
├── audio/
│   └── dyad-040_ses-1_task-conv_run-1_audio.wav
└── transcript/
    └── dyad-040_ses-1_task-conv_run-1_transcript.csv

Each transcript row is one word with its onset time. These onsets are what featuregen phonemic reads to place features on the timeline.

Untimed words

Whisper occasionally emits a token it cannot place in time (some numerals and symbols). Such tokens appear in the transcript with a blank time. Feature generation keeps them, since they still give context to the language model and parser. They are dropped later, when confoundgen and encoding place rows on the TR grid, since a word with no time cannot be aligned to the BOLD signal.

Speaker turns

encoding requires speaking-turn annotations in your events.tsv files; the other steps work without them. When they are present, each transcript gains a turn_sub column naming which subject held the floor when each word began. See Speaker turns for how to mark them.