| Both sides previous revision Previous revision Next revision | Previous revision |
| dcc:itsol:whisper:running [2025/10/30 10:16] – Added text (incomplete) giulio | dcc:itsol:whisper:running [2026/09/25 10:21] (current) – alba |
|---|
| {{indexmenu_n>3}} | {{indexmenu_n>2}} |
| ===== Running Whisper ===== | |
| |
| To run Whisper on HPC, you need to load an environment into your HPC session and build a script to specify what you want the software to do. The HPC Team has built an interface in their portal to make this task clear and easy for you. For this reason, we will describe how to use the interface in this part of the guide. Should you want to modify the script and the instructions to Whisper beyond what the interface allows you to do, then you are of course free to write your own script or contact [[dcc@rug.nl|dcc@rug.nl]] with your question. | ====== Run a Whisper job ====== |
| |
| To access the interface, log into the HPC portal and scroll down until you see the ''Jobs Wizard'' button shown in the screenshot. Click it to open a new window. | - 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:hb_portal_5.png?direct&900 | }} | {{ :dcc:itsol:whisper:open_app.webm?800x450 |}} |
| |
| In the new window, select the wizard for Whisper. **Note**: As of the writing of this guide, there were only two apps available on this part of the portal. You might see more than two, if new ones have been added by the HPC team. | 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. |
| |
| {{ :dcc:itsol:whisper:hb_portal_6.png?direct&900 | }} | ===== Recommended settings ===== |
| |
| The first part of the interface asks you to specify where you want to save the script you are generating, what the script should be called, and what name to assign to the job when it runs. If you have followed this guide until this point, you can leave this part unchanged and move on to the next screenshot. If you have not followed the previous part of this guide, then the one requirement you need to fulfil for this part to work, is that the location where you want to save the script exists. To ensure this, select ''Select Path'', then follow the instructions until you find the folder you want to use. Finally, you can leave the script content hidden, as it is irrelevant if you use the interface. | The form is filled in from top to bottom. For a normal transcription, use these settings: |
| |
| {{ :dcc:itsol:whisper:hb_portal_7.png?direct&900 | }} | ^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 second part of the interface is where you will select the instructions you wish to pass on to Whisper. Here is the explanation of the entry fields as they are numbered: | 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. |
| - **GPU type**: | |
| - **Maximum hours/minutes**: | |
| - **Task**: | |
| - **Language**: | |
| - **Show advanced option**: | |
| - **Folder for input files**: | |
| - **Folder for output files**: | |
| |
| {{ :dcc:itsol:whisper:hb_portal_8a.png?direct&900 | }} | These are starting values rather than guarantees. Long recordings, multiple files, or busy queue conditions may require more time. |
| |
| When you are done setting the instructions, press ''Submit'' to start the transcription job. | 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%%''. |
| |
| For those users that need the transcription to be done following a certain style, here is the option to add a prompt to the Whisper script. Please note that it might be necessary to try out a few prompts before the transcription works the way you want it to. We advise to choose a relatively short audio to experiment on, before launching the main job. | {{ :dcc:itsol:whisper:fill_form.webm?800x450 |}} |
| |
| {{ :dcc:itsol:whisper:hb_portal_8b.png?direct&900 | }} | ===== The job header ===== |
| |
| Once you are done creating the script and you pressed ''Submit'', your job will have been added to the HPC queue. What this means is that your job will start running as soon as the requested resources are available in the cluster. This can take some time to happen. We advise to verify that the script is in the queue by selecting ''History'', as shown in the screenshot. This will direct you to a new window. | The first four fields describe the job itself rather than the transcription. |
| |
| {{ :dcc:itsol:whisper:hb_portal_9.png?direct&900 | }} | * ''%%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. |
| |
| In this new window, you will see the details of your job, such as the JobID or the location of the script. What you care about at this stage is the status, as highlighted in the screenshot. There are three statuses you will most likely see: | ===== Maximum runtime ===== |
| * Queued | |
| * Running | |
| * Completed | |
| |
| Once your job shows the status **COMPLETED**, then you can go back to the main HPC page, select your scratch folder as you have done at the beginning of this guide and download the files in the "output" folder. Please verify that the transcription looks acceptable at first glance before deleting your input data. Once this step is completed, please read the next part of this guide, as there are some data management requirements that you need to follow. | ''%%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. |
| |
| {{ :dcc:itsol:whisper:hb_portal_10.png?direct&900 | }} | ===== Task ===== |
| |
| ===== OLD CONTENT ===== | * 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. |
| |
| Now that you have your general script ready, all you have to do to run it is to simply copy the command below into your terminal and press enter: | ===== Language ===== |
| |
| * <code> sbatch whisper_runall.sh </code> | Choose the language that is spoken in the recording. This usually gives more predictable results than automatic detection. |
| |
| The terminal will then confirm that your job has been received and assign it a ''jobID''. The three messages below will appear in your terminal. | 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. |
| |
| <code> | 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. |
| sbatch: Job sent to gpu partition | |
| sbatch: Request for one of the default GPU types added | |
| Submitted batch job <jobID> | |
| </code> | |
| |
| Please keep the ''jobID'' handy, as that is the quickest way to check how the job is going and if it ran successfully. The figure below shows what the terminal will look like upon successfully launching the script. {{ :dcc:itsol:whisper:run_1a.png?direct&600 | }} | ===== Skip alignment ===== |
| |
| Once the job is complete, you will find the transcribed audio in the output folder you specified in the batch script. | Alignment improves the timing of words and subtitle segments after transcription. Leave ''%%Skip alignment%%'' cleared for normal use. |
| |
| **Note**: The script shown here will **run Whisper on all audio files present in the folder ''whisper_audio''**. Please make sure to **only have the files that you wish to transcribe** in that folder. | Select ''%%Skip alignment%%'' when: |
| |
| To check if the HPC has finished your job, type the following as shown in the figure below: | * the job reports an alignment-model error; |
| | * the selected language has no compatible alignment model; or |
| | * support specifically asks you to bypass alignment. |
| |
| * <code> jobinfo <jobID> </code> | The transcript can still be created without alignment, but word-level timings and subtitle timing may be less precise. |
| {{ :dcc:itsol:whisper:run_2a.png?direct&600 | }} | |
| |
| This will show a list of all the information related to the job. What you want to check is if the "State" parameter says "COMPLETED", and if the "Reserved walltime" is greater than the "Used walltime". If both these values are as described here, it means that the HPC has finished processing your audio and that the job ran correctly. {{ :dcc:itsol:whisper:run_3a.png?direct&600 | }} | 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. |
| |
| If you have launched multiple jobs (which we do not recommend), or if you simply want to see if the job is done without displaying the details of it, type in the following: | ===== Run speaker diarization ===== |
| |
| * <code> squeue -u (your_pnumber) </code> | 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%%''. |
| |
| This command **displays all the active jobs** linked to your account. In the list that will appear, look for the ''jobID'' that you recorded and, under the column ''ST'', read the letter written there. ''PD'' means the job is waiting for resources to be available, ''R'' means that the job is running, ''CG'' means that the job is completing. If your job does not appear in this list, it means that the HPC cluster has finished processing your audio. | 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. |
| |
| [[dcc:itsol:whisper:datamanage| → Move to the next step]] | 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> |
| |