VSpell
A simple, command-line voice spelling and transcription tool. Record a short audio clip, get it transcribed by Whisper, and have the text automatically copied to your clipboard.
VSpell listens for a few seconds, transcribes what it hears using the faster-whisper library, and copies the resulting text directly to your clipboard, streamlining voice-to-text workflows.
Features
- Fast Transcription: Quickly record and transcribe audio using the highly efficient
faster-whisperlibrary. - Clipboard Integration: Transcribed text is automatically copied to the clipboard for immediate pasting.
- Silence Detection: Avoids processing and transcribing empty audio clips, saving time and resources.
- Noise Calibration: Includes a one-time calibration step to accurately distinguish speech from ambient noise.
- Model Selection: Choose from different Whisper model sizes (
tiny,base,small,medium,large) to balance speed and accuracy. - Audio Playback: Listen to your last recording to verify what was captured.
Installation
Before installing, ensure you have the necessary system dependencies for audio recording.
For macOS:
brew install ffmpeg
For Debian/Ubuntu:
sudo apt-get install ffmpeg
To install VSpell, clone this repository and install the package using pip.
git clone https://github.com/vibe-technologies/vspell.git
cd vspell
pip install .
This will install the necessary dependencies and make the vspell command available in your terminal.
First-Time Setup: Calibration
For VSpell to work effectively, it needs to know what "silence" sounds like in your environment. Run the calibration command once before you start using it.
Find a quiet moment and run:
vspell --calibrate
Remain silent for the 2-second duration. This will measure your ambient noise level and set a threshold for silence detection. This value is saved in ~/.config/vspell/vspell_config.json. You can re-run this anytime your environment changes (e.g., you get a new microphone or move to a noisier room).
Usage
Once calibrated, using VSpell is simple.
Main Command
Just run the vspell command. It will listen for 2 seconds, transcribe what it hears, and copy the result to your clipboard.
vspell
Listening for 2 seconds...
Transcribing…
Transcribed: Hello, world.
Text copied to clipboard.
If you say nothing, it will detect the silence and stop.
vspell
Listening for 2 seconds...
No speech detected — nothing transcribed.
Command-Line Options
usage: vspell [-h] [--calibrate] [--playback [PLAYBACK]] [--duration DURATION] [--model MODEL]
VSpell - Voice spelling tool
options:
-h, --help show this help message and exit
--calibrate Calibrate ambient noise threshold
--punctuate Retain punctuation and original casing in transcribed text (default is to remove punctuation and lowercase)
--playback [PLAYBACK]
Playback recorded audio with optional volume
multiplier (default=1.0)
--duration DURATION Recording duration in seconds
--model MODEL Whisper model size [tiny, base, small, medium, large]
(default=medium)
Examples:
-
Record for 5 seconds:
vspell --duration 5
-
Use a different model for higher accuracy (e.g.,
large):vspell --model large
-
Playback the last recording at 1.5x volume:
vspell --playback 1.5
-
Transcribe text with punctuation and original casing:
vspell --punctuate
How It Works
- Record: When you run
vspell, it records audio from your default microphone for a set duration (default is 2 seconds) into a temporary.wavfile. - Analyze: It checks the audio's amplitude against the calibrated silence threshold. If it's below the threshold, the program exits.
- Transcribe: If speech is detected, the audio is passed to the
faster-whispermodel for transcription. The first time you use a model, it will be downloaded and cached locally in~/.cache/huggingface/hub. - Copy: The resulting text is copied to your system's clipboard.
Configuration
VSpell creates a configuration directory at ~/.config/vspell.
~/.config/vspell/vspell_config.json: Stores thesilence_thresholddetermined during calibration.~/.config/vspell/input.wav: The temporary audio file of your last recording.
Metadata
Release files for vspell 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vspell-0.1.4.tar.gz | 9.3 kB | Without provenance | Details for vspell-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vspell-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for vspell-0.1.4-py3-none-any.whl |
Total release size: 18.1 kB
Release files / vspell-0.1.4.tar.gz
| Download URL | vspell-0.1.4.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
44e13b672419a7490e0feb12159dbe080642bf5fa0e2cfcf46175e78650912cb
|
|
BLAKE2b-256 checksum How to use checksums |
d92a64897dbd996cdfe2990b3fb7033739226f2b0f465c89ab93c773cd564a11
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / vspell-0.1.4-py3-none-any.whl
| Download URL | vspell-0.1.4-py3-none-any.whl |
|---|---|
| Size | 8.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
be2758771a80c9ee01d24f32067b9d4e7552b2f83b8f57195d88b299a2faa026
|
|
BLAKE2b-256 checksum How to use checksums |
33e1792599af8d08ca8224467ea26ee9487b8080e1a29b8808453d0370bf4907
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for vspell 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.