Run a Whisper job [CIT Research Documentation]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{indexmenu_n>2}}

====== Run a Whisper job ======

  - Log in to the [[https://portal.hb.hpc.rug.nl/|Hábrók web portal]]. The dashboard opens.
  - Scroll down to ''%%Pinned Apps%%'' and click the ''%%Jobs Wizard%%'' tile under ''%%Batch Apps%%''. The wizard opens in a new browser tab.
  - Click ''%%Whisper%%''. The Whisper form opens.
  - Complete the form as described below.

{{ :dcc:itsol:whisper:open_app.webm?800x450 |}}

The wizard opens in a new browser tab, and the dashboard stays open in the first one, so you can switch back to it at any time.

===== Recommended settings =====

The form is filled in from top to bottom. For a normal transcription, use these settings:

^Field                                         ^Recommended starting value            ^
|''%%Script Location%%''                       |The default ''%%whisper/%%'' directory|
|''%%Script Name%%''                           |''%%jobscript.sh%%''                  |
|''%%Job Name%%''                              |A name that identifies the recording  |
|''%%Hide script content%%''                   |Selected                              |
|''%%Maximum hours%%'', ''%%Maximum minutes%%''|''%%4%%'' and ''%%0%%''               |
|''%%Task%%''                                  |''%%Transcribe%%''                    |
|''%%Language%%''                              |The language spoken in the recording  |
|''%%Skip alignment%%''                        |Not selected                          |
|''%%Run speaker diarization%%''               |Not selected unless you need it       |
|''%%Folder for input files%%''                |Your ''%%whisper/input%%'' directory  |
|''%%Folder for output files%%''               |Your ''%%whisper/output%%'' directory |
|''%%Show advanced options%%''                 |Not selected                          |

The settings above are recommended because naming the language avoids detection mistakes, alignment costs little and gives better timings, and diarization is slower and only worth running when you need speaker labels. A 4-hour limit covers a single recording of ordinary length while keeping the wait in the queue short.

These are starting values rather than guarantees. Long recordings, multiple files, or busy queue conditions may require more time.

Fields marked with an asterisk on screen must be filled in. Several fields stay hidden until you need them, so the form is shorter than the list above suggests until you select ''%%Run speaker diarization%%'' or ''%%Show advanced options%%''.

{{ :dcc:itsol:whisper:fill_form.webm?800x450 |}}

===== The job header =====

The first four fields describe the job itself rather than the transcription.

  * ''%%Script Location%%'' is where the portal writes the job script. The default is a ''%%whisper/%%'' directory in your scratch space. If you followed this guide, leave it as it is; otherwise, use ''%%Select Path%%'' to choose another directory, but never the ''%%input%%'' directory.
  * ''%%Script Name%%'' is the file name of that script. The default ''%%jobscript.sh%%'' is fine.
  * ''%%Job Name%%'' is the name you will see in the portal's job history. The default is ''%%Whisper%%''. A name that identifies the recording makes several jobs easier to tell apart.
  * ''%%Hide script content%%'' is selected by default, which keeps the generated job script out of sight. Clear it if you want to read the script before submitting, for example to compare it with the script of an earlier job. The script is generated for you and everything in this guide works without touching it. If you know your way around Slurm you can edit it before you submit — to request a GPU other than the V100 the app asks for by default, for example.

===== Maximum runtime =====

''%%Maximum hours%%'' and ''%%Maximum minutes%%'' set a limit, not a prediction. The default is 4 hours. A job that reaches its limit is stopped even if transcription has not finished, and the form accepts at most 7 hours and 59 minutes.

===== Task =====

  * Choose ''%%Transcribe%%'' to write the speech in its original language.
  * Choose ''%%Translate%%'' to translate the speech into English while creating the transcript.

Changing the task also selects the matching Whisper model. The model is determined by the task and cannot be changed; it is shown, but not editable, in the advanced options.

===== Language =====

Choose the language that is spoken in the recording. This usually gives more predictable results than automatic detection.

The field is marked as required, but the list starts with an empty entry, and that entry is accepted. Leave the language empty only when you do not know it. Automatic detection can make mistakes, especially for short recordings, background speech, closely related languages, or a strong and uncommon accent: a strongly accented English speaker could be detected as Welsh, for example.

For recordings containing several languages, results may vary. If possible, split the recording into language-specific parts and process each part with the matching language selected.

===== Skip alignment =====

Alignment improves the timing of words and subtitle segments after transcription. Leave ''%%Skip alignment%%'' cleared for normal use.

Select ''%%Skip alignment%%'' when:

  * the job reports an alignment-model error;
  * the selected language has no compatible alignment model; or
  * support specifically asks you to bypass alignment.

The transcript can still be created without alignment, but word-level timings and subtitle timing may be less precise.

A few languages use a language-specific alignment model that the app configures for you; all others use the default model that comes with the alignment step. You never need to enter a model name yourself.

===== Run speaker diarization =====

Speaker diarization attempts to identify when different people are speaking. Select ''%%Run speaker diarization%%'' when speaker labels are useful. The checkbox itself is labelled ''%%Diarize%%''.

The labels identify speakers by number, such as ''%%SPEAKER_00%%'' and ''%%SPEAKER_01%%''. They do not identify people by name, and speaker changes may be wrong when people overlap, interrupt each other, or sound similar.

Selecting the checkbox reveals ''%%Pyannote Model for diarization%%''. Use the default ''%%Community 1 (local)%%'' model unless support has advised otherwise.

Choosing ''%%3.1 (requires HF token)%%'' reveals a further ''%%HuggingFace token%%'' field, and the job will not start until you fill it in. Do not share that token or include it in support messages, screenshots, or copied job scripts. **This is a legacy model which will be removed in the near future**.

===== Input and output directories =====

Both directories default to a ''%%whisper/input/%%'' and a ''%%whisper/output/%%'' directory in your ''%%scratch%%'' space, and ''%%Select Path%%'' opens a browser to choose another. Confirm that:

  * the ''%%input%%'' directory contains the recordings to process;
  * the ''%%output%%'' directory exists; and
  * the two fields do not accidentally point to the same directory.

The app hands every entry in the ''%%input%%'' directory to Whisper, so that directory must hold recordings and nothing else: no job script, no job log, and no results from an earlier run. That is also why the ''%%output%%'' directory is a separate one. If results were written back into the ''%%input%%'' directory, the next job would try to transcribe them.

The job stops with an error if the ''%%input%%'' directory does not exist, so create it before submitting.

===== Advanced options =====

Most users should leave ''%%Show advanced options%%'' cleared. Selecting it reveals:

  * ''%%Initial prompt to Whisper%%'' can provide spelling or context hints, such as names or specialist terminology. Write it as a sentence in the language of the recording, for example ''%%Interview about the Hábrók cluster with Castor and Pollux, mentioning Slurm, WhisperX and scratch storage.%%'' An initial prompt is guidance, not a guaranteed vocabulary list. Keep it short and check whether it improves the result on a sample recording.
  * ''%%Whisper model%%'' shows the model the selected task will use. The field accepts typing but reverts immediately; the model is set by the task and cannot be changed.
  * ''%%Alignment model%%'' appears only when the language you selected has a language-specific alignment model, and it is filled in for you. For every other language, the field stays hidden, and the default alignment model is used.

===== Submit and monitor the job =====

Click ''%%Submit%%'' at the bottom of the form. If you want to read or change the job script first, clear ''%%Hide script content%%'' in the job header.

Submitting does not take you anywhere: the form stays open, and a message at the top of the page confirms that the job has been submitted and offers a ''%%History page%%'' link. Follow it, or open ''%%History%%'' from the portal's menu. Either way, you reach the same list, with one row per job you have submitted:

^Column                 ^What it shows                                         ^
|''%%Job ID%%''         |The scheduler's identifier, which support will ask for|
|''%%Application%%''    |''%%Whisper%%''                                       |
|''%%Script Location%%''|The directory holding the job script and the job log  |
|''%%Script Name%%''    |The generated script, normally ''%%jobscript.sh%%''   |
|''%%Job Name%%''       |The name you gave the job on the form                 |
|''%%Partition%%''      |The queue the job was placed in, chosen for you       |
|''%%Submission Time%%''|When you submitted the job                            |
|''%%Status%%''         |The current state                                     |

Note the ''%%Job ID%%''. You need it to find the job log and to report a problem.

The status normally moves from ''%%Queued%%'', through ''%%Running%%'', to ''%%Completed%%'', or to ''%%Failed%%'' if the job stopped because of an error or ''%%Timeout%%'' if it reached the maximum runtime you set.

Several cells in the row are links:

  * ''%%Job ID%%'' opens a ''%%Job Details%%'' window holding the scheduler's full record of the job, including ''%%State%%'', ''%%Elapsed%%'', ''%%Timelimit%%'', ''%%ExitCode%%'' and ''%%Reason%%''. This is the record support will ask you to quote.
  * ''%%Script Name%%'' opens a ''%%Job Script%%'' window showing the script that was submitted.
  * ''%%Script Location%%'' opens that directory in the file browser. This is where the job log is written.
  * ''%%Application%%'' opens the Whisper form again.

The small icon beside the script location opens a command-line session in that directory. You do not need it for anything in this guide.

A queued job is not necessarily stuck. It may be waiting for the required V100 GPU resources; the ''%%Reason%%'' field in the ''%%Job Details%%'' window says what it is waiting for. Do not submit the same job a second time: the duplicate occupies a second GPU and writes the same output files, so the two jobs overwrite each other's results.

''%%Completed%%'' means that the batch job ended without a scheduler failure. It does not mean the transcript is accurate. Check both the output files and the job log.

{{ :dcc:itsol:whisper:submit.webm?800x450 |}}

<WRAP half column>[[dcc:itsol:whisper:setup|← Previous: Before You Start]]</WRAP>
<WRAP half column rightalign>[[dcc:itsol:whisper:results|Next: Find and Review the Results →]]</WRAP>
<WRAP clear></WRAP>