{"id":13699245,"url":"https://github.com/petewarden/spchcat","last_synced_at":"2025-04-06T01:07:36.804Z","repository":{"id":39342565,"uuid":"442925287","full_name":"petewarden/spchcat","owner":"petewarden","description":"Speech recognition tool to convert audio to text transcripts, for Linux and Raspberry Pi.","archived":false,"fork":false,"pushed_at":"2022-07-01T05:11:51.000Z","size":910,"stargazers_count":461,"open_issues_count":18,"forks_count":34,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-03-30T00:06:50.474Z","etag":null,"topics":["linux","raspberry-pi","speech-recognition"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petewarden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-30T00:32:55.000Z","updated_at":"2025-03-17T16:51:30.000Z","dependencies_parsed_at":"2022-07-12T17:52:23.202Z","dependency_job_id":null,"html_url":"https://github.com/petewarden/spchcat","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petewarden%2Fspchcat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petewarden%2Fspchcat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petewarden%2Fspchcat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petewarden%2Fspchcat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petewarden","download_url":"https://codeload.github.com/petewarden/spchcat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419860,"owners_count":20936012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","raspberry-pi","speech-recognition"],"created_at":"2024-08-02T20:00:28.078Z","updated_at":"2025-04-06T01:07:36.788Z","avatar_url":"https://github.com/petewarden.png","language":"C","funding_links":[],"categories":["C","[Libraries](#libraries)"],"sub_categories":[],"readme":"# Spchcat\n\nSpeech recognition tool to convert audio to text transcripts, for Linux and Raspberry Pi.\n\n## Description\n\n\u003ca href=\"https://tenor.com/view/cat-smiling-awkward-smile-sonrisa-gif-11170177\"\u003e\u003cimg height=\"120px\" style=\"float:left; margin-right: 10px;\" src=\"https://c.tenor.com/wX3b9R6sb90AAAAC/cat-smiling.gif\"/\u003e\u003c/a\u003e\n\n[`spchcat`](https://github.com/petewarden/spchcat) is a command-line tool that reads in audio from .WAV files, a microphone, or system audio inputs and converts any speech found into text. It runs locally on your machine, with no web API calls or network activity, and is open source. It is built on top of [Coqui's speech to text library](https://github.com/coqui-ai/STT), [TensorFlow](https://www.tensorflow.org/), [KenLM](https://kheafield.com/code/kenlm/), and [data from Mozilla's Common Voice project](https://commonvoice.mozilla.org/).\n\nIt supports multiple languages thanks to [Coqui's library of models](https://github.com/coqui-ai/STT-models). The accuracy of the recognized text will vary widely depending on the language, since some have only small amounts of training data. You can help improve future models by [contributing your voice](https://commonvoice.mozilla.org/).\n\n## Installation\n\n### x86\n\nOn Debian-based x86 Linux systems like Ubuntu you should be able to install [the latest .deb package](https://github.com/petewarden/spchcat/releases/download/v0.0.2-alpha/spchcat_0.0-2_amd64.deb) by downloading and double-clicking it. Other distributions are currently unsupported. The tool requires PulseAudio, which is already present on most desktop systems, but can be [installed manually](https://wiki.debian.org/PulseAudio).\n\nThere's a notebook you can run in Colab at [notebooks/install.ipynb](https://github.com/petewarden/spchcat/blob/main/notebooks/install.ipynb) that shows all installation steps.\n\n### Raspberry Pi\n\nTo install on a Raspberry Pi, download the [latest .deb installer package](https://github.com/petewarden/spchcat/releases/download/v0.0.2-rpi-alpha/spchcat_0.0-2_armhf.deb) and either double-click on it from the desktop, or run `dpkg -i ~/Downloads/spchcat_0.0-2_armhf.deb` from the terminal. It will take several minutes to unpack all the language files. This version has only been tested on the latest release of Raspbian, released October 30th 2021, and on a Raspberry Pi 4. It's expected to fail on Raspberry Pi 1's and 0's, due to their CPU architecture.\n\n## Usage\n\nAfter installation, you should be able to run it with no arguments to start capturing audio from the default microphone source, with the results output to the terminal:\n\n```bash\nspchcat\n```\n\nAfter you've run the command, start speaking, and you should see the words you're saying appear. The speech recognition is still a work in progress, and the accuracy will depend a lot on the noise levels, your accent, and the complexity of the words, but hopefully you should see something close enough to be useful for simple note taking or other purposes.\n\n### System Audio\n\nIf you don't have a microphone attached, or want to transcribe audio coming from another program, you can set the `--source` argument to 'system'. This will attempt to listen to the audio that your machine is playing, including any videos or songs, and transcribe any speech found.\n\n```bash\nspchcat --source=system\n```\n\n### WAV Files\n\nOne of the most common audio file formats is WAV. If you don't have any to test with, you can download [Coqui's test set](https://github.com/coqui-ai/STT/releases/download/v1.1.0/audio-1.1.0.tar.gz) to try this option out. If you need to convert files from another format like '.mp3', I recommend using [FFMPeg](https://www.ffmpeg.org/). As with the other source options, `spchcat` will attempt to find any speech in the files and convert it into a transcript. You don't have to explicitly set the `--source` argument, as long as file names are present on the command line that will be the default.\n\n```bash\nspchcat audio/8455-210777-0068.wav \n```\n\nIf you're using the audio file from the test set, you should see output like the following:\n\n```bash\nTensorFlow: v2.3.0-14-g4bdd3955115\n Coqui STT: v1.1.0-0-gf3605e23\nyour power is sufficient i said \n```\n\nYou can also specify a folder instead of a single filename, and all `.wav` files within that directory will be transcribed.\n\n### Language Support\n\nSo far this documentation has assumed you're using American English, but the tool will default to looking for the language your system has been configured to use. It first looks for the one specified in the `LANG` environment variable. If no model for that language is found, it will default back to 'en_US'. You can override this by setting the `--language` argument on the command line, for example:\n\n```bash\nspchcat --language=de_DE\n```\n\nThis works independently of `--source` and other options, so you can transcribe microphone, system audio, or files in any of the supported languages. It should be noted that some languages have very small amounts of data and so their quality may suffer. If you don't care about country-specific variants, you can also just specify the language part of the code, for example `--language=en`. This will pick any model that supports the language, regardless of country. The same thing happens if a particular language and country pair isn't found, it will log a warning and fall back to any country that supports the language. For example, if 'en_GB' is specified but only 'en_US' is present, 'en_US' will be used.\n\n| Language Name | Code    |\n| ------------: |:-------------|\n|am_ET|Amharic|\n|bn_IN|Bengali|\n|br_FR|Breton|\n|ca_ES|Catalan|\n|cnh_MM|Hakha-Chin|\n|cs_CZ|Czech|\n|cv_RU|Chuvash|\n|cy_GB|Welsh|\n|de_DE|German|\n|dv_MV|Dhivehi|\n|el_GR|Greek|\n|en_US|English|\n|et_EE|Estonian|\n|eu_ES|Basque|\n|fi_FI|Finnish|\n|fr_FR|French|\n|fy_NL|Frisian|\n|ga_IE|Irish|\n|hu_HU|Hungarian|\n|id_ID|Indonesian|\n|it_IT|Italian|\n|ka_GE|Georgian|\n|ky_KG|Kyrgyz|\n|lg_UG|Luganda|\n|lt_LT|Lithuanian|\n|lv_LV|Latvian|\n|mn_MN|Mongolian|\n|mt_MT|Maltese|\n|nl_NL|Dutch|\n|or_IN|Odia|\n|pt_PT|Portuguese|\n|rm_CH|Romansh-Sursilvan|\n|ro_RO|Romanian|\n|ru_RU|Russian|\n|rw_RW|Kinyarwanda|\n|sah_RU|Sakha|\n|sb_DE|Upper-Sorbian|\n|sl_SI|Slovenian|\n|sw_KE|Swahili-Congo|\n|ta_IN|Tamil|\n|th_TH|Thai|\n|tr_TR|Turkish|\n|tt_RU|Tatar|\n|uk_UK|Ukrainian|\n|wo_SN|Wolof|\n|yo_NG|Yoruba|\n\nAll of these models have been collected by Coqui, and contributed by organizations like [Inclusive Technology for Marginalized Languages](https://itml.cl.indiana.edu/) or individuals. All are using the conventions for Coqui's STT library, so custom models could potentially be used, but training and deployment of those is outside the scope of this document. The models themselves are provided under a variety of open source licenses, which can be inspected in their source folders (typically inside `/etc/spchcat/models/`).\n\n### Saving Output\n\nBy default `spchcat` writes any recognized text to the terminal, but it's designed to behave like a normal Unix command-line tool, so it can also be written to a file using indirection like this:\n\n```bash\nspchcat audio/8455-210777-0068.wav \u003e /tmp/transcript.txt\n```\n\nIf you then run `cat /tmp/transcript.txt` (or open it in an editor) you should see `your power is sufficient i said'. You can also pipe the output to another command. Unfortunately you can't pipe audio into the tool from another executable, since pipes aren't designed for non-text data. \n\nThere is one subtle difference between writing to a file and to the terminal. The transcription itself can take some time to settle into a final form, especially when waiting for long words to finish, so when it's being run live in a terminal you'll often see the last couple of words change. This isn't useful when writing to a file, so instead the output is finalized before it's written. This can introduce a small delay when writing live microphone or system audio input.\n\n## Build from Source\n\n### Tool\n\nIt's possible to build all dependencies from source, but I recommending downloading binary versions of Coqui's STT, TensorFlow Lite, and KenLM libraries from [github.com/coqui-ai/STT/releases/download/v1.1.0/native_client.tflite.Linux.tar.xz](https://github.com/coqui-ai/STT/releases/download/v1.1.0/native_client.tflite.Linux.tar.xz). Extract this to a folder, and then from inside a folder containing this repo run to build the `spchcat` tool itself:\n\n```bash\nmake spchcat LINK_PATH_STT=-L../STT_download\n```\n\nYou should replace `../STT_download` with the path to the Coqui library folder. After this you should see a `spchcat` executable binary in the repo folder. Because it relies on shared libraries, you'll need to specify a path to these too using `LD_LIBRARY_PATH` unless you have copies in system folders.\n\n```bash\nLD_LIBRARY_PATH=../STT_download ./spchcat\n```\n\n### Models\n\nThe previous step only built the executable binary itself, but for the complete tool you also need data files for each language. If you have the [`gh` GitHub command line tool](https://cli.github.com/) you can run the `download_models.py` script to fetch [Coqui's releases](https://github.com/coqui-ai/STT-models/releases) into the `build/models` folder in your local repo. You can then run your locally-built tool against these models using the `--languages_dir` option:\n\n```bash\nLD_LIBRARY_PATH=../STT_download ./spchcat --languages_dir=build/models/\n```\n\n### Installer\n\nAfter you have the tool built and the model data downloaded, `create_deb_package.sh` will attempt to package them into a Debian installer archive. It will take several minutes to run, and the result ends up in `spchcat_0.0-2_amd64.deb`.\n\n### Release Process\n\nThere's a notebook at [notebooks/build.pynb](https://github.com/petewarden/spchcat/blob/main/notebooks/build.ipynb) that runs through all the build steps needed to downloaded dependencies, data, build the executable, and create the final package. These steps are run inside an Ubuntu 18.04 Docker image to create [the binaries that are released](https://github.com/petewarden/spchcat/releases).\n\n```bash\nsudo docker run -it -v`pwd`:/spchcat ubuntu:bionic bash\n```\n\n## Contributors\n\nTool code written by [Pete Warden](https://twitter.com/petewarden), pete@petewarden.com, heavily based on [Coqui's STT example](https://github.com/coqui-ai/STT/blob/main/native_client/stt.cc). It's a pretty thin wrapper on top of [Coqui's speech to text library](https://github.com/coqui-ai/STT), so the Coqui team should get credit for their amazing work. Also relies on [TensorFlow](https://www.tensorflow.org/), [KenLM](https://kheafield.com/code/kenlm/), [data from Mozilla's Common Voice project](https://commonvoice.mozilla.org/), and all the contributors to [Coqui's model zoo](https://coqui.ai/models).\n\n## License\n\nTool code is licensed under the Mozilla Public License Version 2.0, see LICENSE in this folder.\n\nAll other libraries and model data are released under their own licenses, see the relevant folders for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetewarden%2Fspchcat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetewarden%2Fspchcat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetewarden%2Fspchcat/lists"}