Configuration

Configure hns to match your hardware and transcription needs. By configuring the Whisper model and language, you can significantly improve transcription accuracy, optimize for speed, and tailor hns's performance to your specific requirements.

Model Selection: HNS_WHISPER_MODEL

This environment variable controls which Whisper model hns uses for transcription. The default is base, but you can choose from several others based on your needs.

To set it, you can define the environment variable in your shell.

bash/zsh

Temporary (current session only):

export HNS_WHISPER_MODEL="distil-large-v3.5"
hns

Permanent:

Add the following line to your shell's configuration file.

~/.bashrc or ~/.zshrc

export HNS_WHISPER_MODEL="distil-large-v3.5"

Then, reload your shell's configuration:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

fish

Temporary (current session only):

set -x HNS_WHISPER_MODEL "distil-large-v3.5"
hns

Permanent:

Add the following line to your Fish configuration file.

~/.config/fish/config.fish

set -gx HNS_WHISPER_MODEL "distil-large-v3.5"

Then, reload your shell's configuration:

source ~/.config/fish/config.fish

Available Models

Here are the models you can choose from. They are hosted on Hugging Face by Systran and other contributors.

Model Name	Size	Type
tiny.en	~75MB	English only
tiny	~75MB	Multilingual
base.en	~145MB	English only
base	~145MB	Multilingual
small.en	~484MB	English only
small	~484MB	Multilingual
medium.en	~1.53GB	English only
medium	~1.53GB	Multilingual
large-v1	~3.09GB	Multilingual
large-v2	~3.09GB	Multilingual
large-v3	~3.09GB	Multilingual
large	~3.09GB	Multilingual
distil-large-v2	~1.51GB	Multilingual
distil-medium.en	~789MB	English only
distil-small.en	~332MB	English only
distil-large-v3	~1.51GB	Multilingual
distil-large-v3.5	~1.51GB	Multilingual
large-v3-turbo	~1.62GB	Multilingual
turbo	~1.62GB	Multilingual

Model Recommendations

Which model to use?

• Best Overall: distil-large-v3.5 is the recommended choice for most users. It offers accuracy close to large-v3 with about half the RAM usage (~1.5GB) and is ~6x faster. It produces high-quality transcriptions with correct punctuation.
• Maximum Accuracy: Use large-v3 when you need the highest accuracy and speed or memory (~3GB RAM) are not concerns.
• Fast & Light: For faster transcription and lower RAM usage (~0.6GB), consider small. It's about 3-4x faster than distil-large-v3.5 with decent accuracy.
• Featherweight: tiny is the smallest and fastest model, suitable for memory-constrained environments.

For English-only transcription, always prefer the .en variants (e.g., small.en). They are more accurate and performant for English than their multilingual counterparts.

Language Selection: HNS_LANG

This variable forces hns to transcribe in a specific language, which can improve accuracy over the default auto-detection, especially for non-English languages.

tip

• While Whisper's auto-detection is powerful, we strongly recommend setting HNS_LANG explicitly. This improves accuracy and prevents potential misidentification of the spoken language.
• Even if you primarily speak English, setting HNS_LANG to en can enhance transcription quality.

Set the variable to the ISO 639-1 code of your target language.

bash/zsh

Temporary (current session only):

export HNS_LANG="ja"
hns

Permanent:

~/.bashrc or ~/.zshrc

export HNS_LANG="ja"

fish

Temporary (current session only):

set -x HNS_LANG "ja"
hns

Permanent:

~/.config/fish/config.fish

set -gx HNS_LANG "ja"

Supported Languages

Whisper officially supports 57 languages (WER < 50%). Use the corresponding ISO 639-1 code when setting HNS_LANG.

Language	Code	Language	Code	Language	Code
Afrikaans	af	German	de	Persian	fa
Arabic	ar	Greek	el	Polish	pl
Armenian	hy	Hebrew	he	Portuguese	pt
Azerbaijani	az	Hindi	hi	Romanian	ro
Belarusian	be	Hungarian	hu	Russian	ru
Bosnian	bs	Icelandic	is	Serbian	sr
Bulgarian	bg	Indonesian	id	Slovak	sk
Catalan	ca	Italian	it	Slovenian	sl
Chinese	zh	Japanese	ja	Spanish	es
Croatian	hr	Kannada	kn	Swahili	sw
Czech	cs	Kazakh	kk	Swedish	sv
Danish	da	Korean	ko	Tagalog	tl
Dutch	nl	Latvian	lv	Tamil	ta
English	en	Lithuanian	lt	Thai	th
Estonian	et	Macedonian	mk	Turkish	tr
Finnish	fi	Malay	ms	Ukrainian	uk
French	fr	Marathi	mr	Urdu	ur
Galician	gl	Maori	mi	Vietnamese	vi
		Nepali	ne	Welsh	cy

---

Congratulations on customizing your hns setup! Next, explore the use cases to integrate hns into your workflows.