buzz Documentation

Buzz transcribes and translates audio offline on your personal computer. Powered by OpenAI's Whisper.

20,907 stars Python Python 1 file ยท ~7,495 tokens #whisper
RAW Doc

File: README.md

[็ฎ€ไฝ“ไธญๆ–‡] <- ็‚นๅ‡ปๆŸฅ็œ‹ไธญๆ–‡้กต้ขใ€‚

Buzz

Documentation

Transcribe and translate audio offline on your personal computer. Powered by
OpenAI's Whisper.


Features

  • Transcribe audio and video files or Youtube links
  • Live realtime audio transcription from microphone
    • Presentation window for easy accessibility during events and presentations
  • Speech separation before transcription for better accuracy on noisy audio
  • Speaker identification in transcribed media
  • Multiple whisper backend support
    • CUDA acceleration support for Nvidia GPUs
    • Apple Silicon support for Macs
    • Vulkan acceleration support for Whisper.cpp on most GPUs, including integrated GPUs
  • Multiple Transformer model family support via Huggingface whisper type
  • Export transcripts to TXT, SRT, and VTT
  • Advanced Transcription Viewer with search, playback controls, and speed adjustment
  • Keyboard shortcuts for efficient navigation
  • Watch folder for automatic transcription of new files
  • Command-Line Interface for scripting and automation
  • Plugin system with plugins like AI summary generation and automated transcript resizing

Installation

macOS

Download the .dmg from the SourceForge.

Windows

Get the installation files from the SourceForge.

App is not signed, you will get a warning when you install it. Select More info -> Run anyway.

Linux

Buzz is available as a Flatpak or a Snap.

To install flatpak, run:

shell
flatpak install flathub io.github.chidiwilliams.Buzz

To install snap, run:

shell
sudo apt-get install libportaudio2 libcanberra-gtk-module libcanberra-gtk3-module
sudo snap install buzz

PyPI

Install ffmpeg

Ensure you use Python 3.12 environment.

Install Buzz

shell
pip install buzz-captions
python -m buzz

GPU support for PyPI

To have GPU support for Nvidia GPUS on Windows, for PyPI installed version ensure, CUDA support for torch

text
pip3 install -U torch==2.8.0+cu129 torchaudio==2.8.0+cu129 --index-url https://download.pytorch.org/whl/cu129
pip3 install nvidia-cublas-cu12==12.9.1.4 nvidia-cuda-cupti-cu12==12.9.79 nvidia-cuda-runtime-cu12==12.9.79 --extra-index-url https://pypi.ngc.nvidia.com

Latest development version

For info on how to get latest development version with latest features and bug fixes see FAQ.

Support Buzz

You can help the Buzz by starring ๐ŸŒŸ the repo and sharing it with your friends.

Screenshots

File: docs/docs/usage/1_file_import.md

title: File Import

To import a file:

  • Click Import Media File on the File menu (or the '+' icon on the toolbar, or Command/Ctrl + O).
  • Choose an audio or video file.
  • Select a task, language, and the model settings.
  • Click Run.
  • When the transcription status shows 'Completed', double-click on the row (or select the row and click the 'โคข' icon) to
    open the transcription.

Available options:

To reduce misspellings you can pass some commonly misspelled words in an Initial prompt that is available under Advanced... button. See this guide on prompting.

Field Options Default Description
Export As "TXT", "SRT", "VTT" "TXT" Export file format
Word-Level Timings Off / On Off If checked, the transcription will generate a separate subtitle line for each word in the audio. Combine words into subtitles afterwards with the resize option.
Extract speech Off / On Off If checked, speech will be extracted to a separate audio tack to improve accuracy.

(See the Live Recording section for more information about the task, language, and quality settings.)

๐Ÿ’ก Tip: It is recommended to always select language to transcribe to as automatic language detection may result in unexpected results.

File: docs/docs/usage/2_live_recording.md

title: Live Recording

To start a live recording:

  • Select a recording task, language, quality, and microphone.
  • Click Record.

Note: Transcribing audio using the default Whisper model is resource-intensive. Consider using the Whisper.cpp.
It supports GPU acceleration, if the model fits in GPU memory. Use smaller models for real-time performance.

Field Options Default Description
Task "Transcribe", "Translate to English" "Transcribe" "Transcribe" converts the input audio into text in the selected language, while "Translate to English" converts it into text in English.
Language See Whisper's documentation for the full list of supported languages "Detect Language" "Detect Language" will try to detect the spoken language in the audio based on the first few seconds. However, selecting a language is recommended (if known) as it will improve transcription quality in many cases.
Microphone [Available system microphones] [Default system microphone] Microphone for recording input audio.

Advanced preferences

Silence threshold Set threshold to for transcriptions to be processed. If average volume level is under this setting the sentence will not be transcribed. Available since 1.4.4.

Line separator Marking to add to the transcription and translation lines. Default value is two new lines (\n\n) that result in an empty space between translation or transcription lines. To have no empty line use \n. Available since 1.4.4.

Transcription step If live recording mode is set to Append and correct, you can also set a transcription step. Shorter steps will reduce latency but cause larger load on the system. Monitor the Queue while transcribing in this mode, if it grows too much, increase the transcription step, to reduce load. Available since 1.4.4.

Hide unconfirmed If live recording mode is set to Append and correct, you can also hide the unconfirmed part of the last transcript. This part may be incorrect as the Buzz has seen it only in one overlapping transcription segment. Hiding it will increase latency, but result will show only the correct transcripts. Available since 1.4.4.

Presentation Window

Buzz has an easy to use presentation window you can use to show live transcriptions during events and presentations. To open it start the recording and new options for the Presentation window will appear.

Record audio playing from computer (macOS)

To record audio playing from an application on your computer, you may install an audio loopback driver (a program that
lets you create virtual audio devices). The rest of this guide will
use BlackHole on Mac, but you can use other alternatives for your
operating system (
see LoopBeAudio, LoopBack,
and Virtual Audio Cable).

  1. Install BlackHole via Homebrew

    shell
    brew install blackhole-2ch

  2. Open Audio MIDI Setup from Spotlight or from /Applications/Utilities/Audio Midi Setup.app.

  3. Click the '+' icon at the lower left corner and select 'Create Multi-Output Device'.

  4. Add your default speaker and BlackHole to the multi-output device.

  5. Select this multi-output device as your speaker (application or system-wide) to play audio into BlackHole.

  6. Open Buzz, select BlackHole as your microphone, and record as before to see transcriptions from the audio playing
    through BlackHole.

Record audio playing from computer (Windows)

To transcribe system audio you need to configure virtual audio device and connect output from the applications you whant to transcribe to this virtual speaker. After that you can select it as source in the Buzz.

  1. Install VB CABLE as virtual audio device.

  2. Configure using Windows Sound settings. Right-click on the speaker icon in the system tray and select "Open Sound settings". In the "Choose your output device" dropdown select "CABLE Input" to send all system sound to the virtual device or use "Advanced sound options" to select application that will output their sound to this device.

Record audio playing from computer (Linux)

As described on Ubuntu Wiki on any Linux with pulse audio you can redirect application audio to a virtual speaker. After that you can select it as source in Buzz.

Overall steps:

  1. Launch application that will produce the sound you want to transcribe and start the playback. For example start a video in a media player.
  2. Launch Buzz and open Live recording screen, so you see the settings.
  3. Configure sound routing from the application you want to transcribe sound from to Buzz in Recording tab of the PulseAudio Volume Control (pavucontrol).

File: docs/docs/usage/3_translations.md

title: Translations

Default Translation task uses Whisper model ability to translate to English, however Large-V3-Turbo is not compatible with this standard. Buzz supports additional AI translations to any other language.

To use translation feature you will need to configure OpenAI API base url and key and translation settings. Set OpenAI API ket in Preferences. For information on available APIs from ChatGPT, Claude or Gemini see this discussion thread.

Buzz also supports custom locally running translation AIs that support OpenAI API. For more information on locally running AIs see ollama or LM Studio. For information on available APIs see this discussion thread.

To configure translation for Live recordings enable it in Advances settings dialog of the Live Recording settings. Enter AI model to use and prompt with instructions for the AI on how to translate. Translation option is also available for files that already have speech recognized. Use Translate button on transcription viewer toolbar.

For AI to know how to translate enter translation instructions in the "Instructions for AI" section. In your instructions you should describe to what language you want it to translate the text to. Also, you may need to add additional instructions to not add any notes or comments as AIs tend to add them. Example instructions to translate English subtitles to Spanish:

You are a professional translator, skilled in translating English to Spanish. You will only translate each sentence sent to you into Spanish and not add any notes or comments.

If you enable "Enable live recording transcription export" in Preferences, Live text transcripts will be exported to a text file as they get generated and translated. This file can be used to further integrate Live transcripts with other applications like OBS Studio.

Approximate cost of translation for 1 hour long audio with ChatGPT or Claude model is around $1.00.

File: docs/docs/usage/4_edit_and_resize.md

title: Edit and Resize

When transcript of some audio or video file is generated you can edit it and export to different subtitle formats or plain text. Double-click the transcript in the list of transcripts to see additional options for editing and exporting.

Transcription view screen has option to resize the transcripts. Click on the "Resize" button so see available options. Transcripts that have been generated with word-level timings setting enabled can be combined into subtitles specifying different options, like maximum length of a subtitle and if subtitles should be split on punctuation. For transcripts that have been generated without word-level timings setting enabled can only be recombined specifying desired max length of a subtitle.

If audio file is still present on the system word-level timing merge will also analyze the audio for silences to improve subtitle accuracy.

The resize tool also has an option to extend end time of segments if you want the subtitles to be on the screen for longer. You can specify the amount of time in seconds to extend each subtitle segment. Buzz will add this amount of time to the end of each subtitle segment making sure that the end of a segment does not go over start of the next segment. This feature is available since 1.4.3.

File: docs/docs/cli.md

title: CLI sidebar_position: 5

Commands

`add`

Start a new transcription task.

text
/* Detailed source-code truncated for AI context efficiency. */

Examples:

shell
# Translate two MP3 files from French to English using OpenAI Whisper API
buzz add --task translate --language fr --model-type openaiapi /Users/user/Downloads/1b3b03e4-8db5-ea2c-ace5-b71ff32e3304.mp3 /Users/user/Downloads/koaf9083k1lkpsfdi0.mp3

# Transcribe an MP4 using Whisper.cpp "small" model and immediately export to SRT and VTT files
buzz add --task transcribe --model-type whispercpp --model-size small --prompt "My initial prompt" --srt --vtt /Users/user/Downloads/buzz/1b3b03e4-8db5-ea2c-ace5-b71ff32e3304.mp4

File: docs/docs/faq.md

title: FAQ sidebar_position: 5

1. Where are the models stored?

The models are stored:

  • Linux: ~/.cache/Buzz
  • Mac OS: ~/Library/Caches/Buzz
  • Windows: %USERPROFILE%\AppData\Local\Buzz\Buzz\Cache

Paste the location in your file manager to access the models or go to Help -> Preferences -> Models and click on Show file location button after downloading some model.

2. What can I try if the transcription runs too slowly?

Speech recognition requires large amount of computation, so one option is to try using a lower Whisper model size or using a Whisper.cpp model to run speech recognition of your computer. If you have access to a computer with GPU that has at least 6GB of VRAM you can try using the Faster Whisper model.

Buzz also supports using OpenAI API to do speech recognition on a remote server. To use this feature you need to set OpenAI API key in Preferences. See Preferences section for more details.

3. How to record system audio?

To transcribe system audio you need to configure virtual audio device and connect output from the applications you want to transcribe to this virtual speaker. After that you can select it as source in the Buzz. See Usage section for more details.

Relevant tools:

4. What model should I use?

Model size to use will depend on your hardware and use case. Smaller models will work faster but will have more inaccuracies. Larger models will be more accurate but will require more powerful hardware or longer time to transcribe.

When choosing among large models consider the following. "Large" is the first released older model, "Large-V2" is later updated model with better accuracy, for some languages considered the most robust and stable. "Large-V3" is the latest model with the best accuracy in many cases, but some times can hallucinate or invent words that were never in the audio. "Turbo" model tries to get a good balance between speed and accuracy. The only sure way to know what model best suits your needs is to test them all in your language.

In addition to choosing an appropriate model size you also can choose whisper type.

  • Whisper is initial OpenAI implementation, it is accurate but slow and requires a lot of RAM.
  • Faster Whisper is an optimized implementation, it is orders of magnitude faster than regular Whisper and requires less RAM. Use this option if you have an Nvidia GPU with at least 6GB of VRAM.
  • Whisper.cpp is optimized C++ implementation, it quite fast and efficient and will use any brand of GPU. Whisper.cpp is capable of running real time transcription even on a modern laptop with integrated GPU. It can also run on CPU only. Use this option if you do not have Nvidia GPU. This is best option to us on Macs.
  • HuggingFace option is a Transformers implementation and is good in that it supports wide range of custom models that may be optimized for a particular language.
    • Since version 1.4.0 This option also supports MMS family of models from Meta AI that support over 1000 of worlds languages as well as PEFT adjustments to Whisper models.
    • Since version 1.5.0 Parakeet, Qwen3-ASR and VibeVoice ASR models are also supported.

Models with .En in their names are for English and will not work for other languages.

5. How to get GPU acceleration for faster transcription?

On Linux GPU acceleration is supported out of the box on Nvidia GPUs. If you still get any issues install CUDA 12, cuBLASS and cuDNN.

On Windows GPU support is included in the installation .exe. CUDA 12 required, computers with older CUDA versions will use CPU. See this note on enabling CUDA GPU support.

6. How to fix `Unanticipated host error[PaErrorCode-9999]`?

Check if there are any system settings preventing apps from accessing the microphone.

On Windows, see if Buzz has permission to use the microphone in Settings -> Privacy -> Microphone.

See method 1 in this video https://www.youtube.com/watch?v=eRcCYgOuSYQ

For method 2 there is no need to uninstall the antivirus, but see if you can temporarily disable it or if there are settings that may prevent Buzz from accessing the microphone.

7. Can I use Buzz on a computer without internet?

Yes, Buzz can be used without internet connection if you download the necessary models on some other computer that has the internet and manually move them to the offline computer. The easiest way to find where the models are stored is to go to Help -> Preferences -> Models. Then download some model, and push "Show file location" button. This will open the folder where the models are stored. Copy the models folder to the same location on the offline computer. F.e. for Linux it is .cache/Buzz/models in your home directory.

Please also check scripts/download-models.py. This is a script that can help you prepare model cache of offline use.

8. Buzz crashes, what to do?

If a model download was incomplete or corrupted, Buzz may crash. Try to delete the downloaded model files in Help -> Preferences -> Models and re-download them.

If that does not help, check the log file for errors and report the issue so we can fix it. If possible attach the log file to the issue. To get to the logs folder go to Help -> About Buzz and click on Show logs button.

Also note that Buzz needs AVX2 support in your CPU, very old computers are not supported.

9. Where can I get latest development version?

Latest development version will have latest bug fixes and most recent features. If you feel a bit adventurous it is recommended to try the latest development version as they needs some testing before they get released to everybody.

  • Linux users can get the latest version with this command sudo snap install buzz --edge

  • For other platforms do the following:

    1. Go to the build section
    2. Click on the link to the latest build, the most recent successful build entry in the list
    3. Scroll down to the artifacts section in the build page
    4. Download the installation file. Please note that you need to be logged in the Github to see the download links.

10. Why is my system theme not applied to Buzz installed from Flatpak?

For dark themes on Gnome environments you may need to install gnome-themes-extra package and set the following preferences:

text
gsettings set org.gnome.desktop.interface gtk-theme Adwaita-dark
gsettings set org.gnome.desktop.interface color-scheme prefer-dark

If your system theme is not applied to Buzz installed from Flatpak Linux app store, ensure the desired theme is in ~/.themes folder.

You may need to copy the system themes to this folder cp -r /usr/share/themes/ ~/.themes/ and give Flatpaks access to this folder flatpak override --user --filesystem=~/.themes.

On Fedora run the following to install the necessary packages
sudo dnf install gnome-themes-extra qadwaitadecorations-qt{5,6} qt{5,6}-qtwayland

11. What libraries does Buzz use internally?

Buzz uses many great libraries and tools internally. A few that we are really glad to have are:

File: docs/docs/index.md

title: Introduction sidebar_position: 1

Transcribe and translate audio offline on your personal computer. Powered by
OpenAI's Whisper.


Features

File: docs/docs/installation.md

title: Installation sidebar_position: 2

To install Buzz, download the latest version for your operating
system. Buzz is available on Mac (Intel and Apple silicon), Windows, and Linux.

macOS

Download the .dmg from the SourceForge.

Windows

Get the installation files from the SourceForge.

App is not signed, you will get a warning when you install it. Select More info -> Run anyway.

Linux

Buzz is available as a Flatpak or a Snap.

To install flatpak, run:

shell
flatpak install flathub io.github.chidiwilliams.Buzz

To install snap, run:

shell
sudo apt-get install libportaudio2 libcanberra-gtk-module libcanberra-gtk3-module
sudo snap install buzz
sudo snap connect buzz:password-manager-service

PyPI

shell
pip install buzz-captions
python -m buzz

On Linux install system dependencies you may be missing

text
sudo apt-get install --no-install-recommends libyaml-dev libtbb-dev libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-shape0 libxcb-cursor0 libportaudio2 gettext libpulse0 ffmpeg

On versions prior to Ubuntu 24.04 install sudo apt-get install --no-install-recommends libegl1-mesa

Explore Related Technologies & Topics

View All 9,111+ Repositories โ†’

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#whisper Browse whisper catalog โ†’ โšก MCP Servers Model Context Protocol โ†’ ๐Ÿง  Agent Skills Prompt & rule files โ†’ ๐Ÿ”Œ OpenAPI Specs REST & Swagger schemas โ†’