scribe-cli 0.3.0__tar.gz

scribe_cli-0.3.0/.github/workflows/pypi.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write  # This is required for OIDC
+      contents: read
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools setuptools-scm[toml] wheel build
+
+    - name: Build distribution
+      run: python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

scribe_cli-0.3.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+*.pyc
+.venv
+build
+dist

scribe_cli-0.3.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2024 Mahé Perrette
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: This project relies on external packages that may have more restrictive
+licenses. For example, the `pynput` package is licensed under LGPLv3, which
+has different requirements compared to the MIT License. Please review the
+licenses of all dependencies before using or distributing this software to
+ensure compliance with their respective terms.

scribe_cli-0.3.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.2
+Name: scribe-cli
+Version: 0.3.0
+Summary: scribe is a local speech recognition tool that provides real-time transcription using vosk and whisper AI.
+Author-email: Mahé Perrette <mahe.perrette@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Mahé Perrette
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        ---
+        
+        Note: This project relies on external packages that may have more restrictive
+        licenses. For example, the `pynput` package is licensed under LGPLv3, which
+        has different requirements compared to the MIT License. Please review the
+        licenses of all dependencies before using or distributing this software to
+        ensure compliance with their respective terms.
+Project-URL: Homepage, https://github.com/perrette/scribe
+Keywords: speech recognition,transcription,AI,language,vosk,whisper,openai
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: sounddevice
+Requires-Dist: tqdm
+Requires-Dist: requests
+Provides-Extra: keyboard
+Requires-Dist: pynput; extra == "keyboard"
+Provides-Extra: whisper
+Requires-Dist: openai-whisper; extra == "whisper"
+Provides-Extra: vosk
+Requires-Dist: vosk; extra == "vosk"
+Provides-Extra: all
+Requires-Dist: pynput; extra == "all"
+Requires-Dist: openai-whisper; extra == "all"
+Requires-Dist: vosk; extra == "all"
+
+# Scribe
+
+`scribe` is a local speech recognition tool that provides real-time transcription using vosk and whisper AI.
+
+## Installation
+
+Install PortAudio library. E.g. on Ubuntu:
+
+```bash
+sudo apt-get install portaudio19-dev
+```
+
+The python dependencies should be dealt with automatically:
+
+```bash
+pip install scribe-cli[all]"
+```
+
+(note the `-cli` suffix for client)
+
+or for local development:
+
+```bash
+git clone https://github.com/perrette/scribe.git
+cd scribe
+pip install -e .[all]
+```
+
+You can leave the optional dependencies (leave out `[all]`) but must install at least one of `vosk` or `openai-whisper` packages (see Usage below).
+
+The `vosk` language models will download on-the-fly.
+The default data folder is `$HOME/.local/share/vosk/language-models`.
+This can be modified.
+
+
+## Usage
+
+Just type in the terminal:
+
+```bash
+scribe
+```
+and the script will guide you through the choice of backend (`whisper` or `vosk`) and the specific language model.
+After this, you will be prompted to start recording your microphone and print the transcribed text in real-time (`vosk`)
+or until after recording is complete (`whisper`).
+You can interrupt the recording via Ctrl + C and start again or change model.
+
+The default (`whisper`) is excellent at transcribing a full-length audio sequences in [many languages](https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages). It is really impressive,
+but it cannot do real-time out of the box, and depending on the model can have relatively long execution time, especially with the `turbo` model (at least on my laptop with CPU only). The `small` model is also excellent and runs much faster. It is selected as default in `scribe` for that reason.
+With the `whisker` model you need to stop the registration manually before the transcription occurs (Ctrl + C), though after
+60 seconds it will stop automatically (and try to continue afterward).
+
+The `vosk` backend is good at
+doing real-time transcription for one language, but tended to make more mistakes in my tests and it does not do punctuation.
+There are many [vosk models](https://alphacephei.com/vosk/models) available, and here a few are associated to [a handful of languages](scribe/models.toml) `en`, `fr`, `it`, `de` (so far).
+
+To skip the initial selection menu you can do:
+```bash
+scribe --backend whisper --model small --no-prompt
+```
+where `--no-prompt` jumps right to the recording (after the first interruption, you can still choose to change the backend and model).
+
+### Advanced usage as keyboard replacement
+
+With the `--keyboard` option `scribe` will attempt to simulate a keyboard and send transcribed characters to the applcation under focus:
+
+```bash
+scribe --keyboard
+```
+
+It relies on the optional `pynput` dependency (installed together with `scribe` if you used the `[all]` or `[keyboard]` option).
+
+`pynput` may require [some configuration](https://pynput.readthedocs.io/en/latest/limitations.html) (I *think* got it to work with `xhost +SI:localuser:$(whoami)` as far as the display is concerned). It has [limitations]((https://pynput.readthedocs.io/en/latest/limitations.html)). In my Ubuntu + Wayland system it works in chromium based applications (including vscode) but it does not in firefox and sublime text and any of the rest (not even in a terminal !).
+Workarounds include using the Xorg version of GNOME... Suggestions welcome.
+
+### Start as an application in Ubuntu
+
+If you run Ubuntu (or else?) with GNOME, the script `scribe-install [...]` will create a `scribe.desktop` file and place it under `$HOME/.local/share/applications`
+to make it available from the quick launch menu. Any option will be passed on to `scribe`.

scribe_cli-0.3.0/README.md

@@ -0,0 +1,79 @@
+# Scribe
+
+`scribe` is a local speech recognition tool that provides real-time transcription using vosk and whisper AI.
+
+## Installation
+
+Install PortAudio library. E.g. on Ubuntu:
+
+```bash
+sudo apt-get install portaudio19-dev
+```
+
+The python dependencies should be dealt with automatically:
+
+```bash
+pip install scribe-cli[all]"
+```
+
+(note the `-cli` suffix for client)
+
+or for local development:
+
+```bash
+git clone https://github.com/perrette/scribe.git
+cd scribe
+pip install -e .[all]
+```
+
+You can leave the optional dependencies (leave out `[all]`) but must install at least one of `vosk` or `openai-whisper` packages (see Usage below).
+
+The `vosk` language models will download on-the-fly.
+The default data folder is `$HOME/.local/share/vosk/language-models`.
+This can be modified.
+
+
+## Usage
+
+Just type in the terminal:
+
+```bash
+scribe
+```
+and the script will guide you through the choice of backend (`whisper` or `vosk`) and the specific language model.
+After this, you will be prompted to start recording your microphone and print the transcribed text in real-time (`vosk`)
+or until after recording is complete (`whisper`).
+You can interrupt the recording via Ctrl + C and start again or change model.
+
+The default (`whisper`) is excellent at transcribing a full-length audio sequences in [many languages](https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages). It is really impressive,
+but it cannot do real-time out of the box, and depending on the model can have relatively long execution time, especially with the `turbo` model (at least on my laptop with CPU only). The `small` model is also excellent and runs much faster. It is selected as default in `scribe` for that reason.
+With the `whisker` model you need to stop the registration manually before the transcription occurs (Ctrl + C), though after
+60 seconds it will stop automatically (and try to continue afterward).
+
+The `vosk` backend is good at
+doing real-time transcription for one language, but tended to make more mistakes in my tests and it does not do punctuation.
+There are many [vosk models](https://alphacephei.com/vosk/models) available, and here a few are associated to [a handful of languages](scribe/models.toml) `en`, `fr`, `it`, `de` (so far).
+
+To skip the initial selection menu you can do:
+```bash
+scribe --backend whisper --model small --no-prompt
+```
+where `--no-prompt` jumps right to the recording (after the first interruption, you can still choose to change the backend and model).
+
+### Advanced usage as keyboard replacement
+
+With the `--keyboard` option `scribe` will attempt to simulate a keyboard and send transcribed characters to the applcation under focus:
+
+```bash
+scribe --keyboard
+```
+
+It relies on the optional `pynput` dependency (installed together with `scribe` if you used the `[all]` or `[keyboard]` option).
+
+`pynput` may require [some configuration](https://pynput.readthedocs.io/en/latest/limitations.html) (I *think* got it to work with `xhost +SI:localuser:$(whoami)` as far as the display is concerned). It has [limitations]((https://pynput.readthedocs.io/en/latest/limitations.html)). In my Ubuntu + Wayland system it works in chromium based applications (including vscode) but it does not in firefox and sublime text and any of the rest (not even in a terminal !).
+Workarounds include using the Xorg version of GNOME... Suggestions welcome.
+
+### Start as an application in Ubuntu
+
+If you run Ubuntu (or else?) with GNOME, the script `scribe-install [...]` will create a `scribe.desktop` file and place it under `$HOME/.local/share/applications`
+to make it available from the quick launch menu. Any option will be passed on to `scribe`.

scribe_cli-0.3.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0", "setuptools_scm[toml]>=6.2", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scribe-cli"
+dynamic = ["version"]
+description = "scribe is a local speech recognition tool that provides real-time transcription using vosk and whisper AI."
+authors = [
+    { name="Mahé Perrette", email="mahe.perrette@gmail.com" }
+]
+readme = "README.md"
+license = { file="LICENSE" }
+requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+    "sounddevice",
+    "tqdm",
+    "requests",
+]
+optional-dependencies = { keyboard = ["pynput"], whisper = ["openai-whisper"], vosk = ["vosk"], all = ["pynput", "openai-whisper", "vosk"] }
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+keywords = [
+    "speech recognition",
+    "transcription",
+    "AI",
+    "language",
+    "vosk",
+    "whisper",
+    "openai",
+]
+
+[tool.setuptools]
+packages = [ "scribe" ]
+
+[tool.setuptools_scm]
+write_to = "scribe/_version.py"
+
+
+[project.urls]
+Homepage = "https://github.com/perrette/scribe"
+
+[project.scripts]
+scribe = "scribe.streamer:main"
+scribe-install = "scribe.install_desktop:main"

scribe_cli-0.3.0/scribe/__init__.py

@@ -0,0 +1 @@
+from ._version import __version__

scribe_cli-0.3.0/scribe/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)

scribe_cli-0.3.0/scribe/audio.py

@@ -0,0 +1,51 @@
+import sounddevice as sd
+import queue
+
+
+def get_duration(audio_length_bytes, # bytes
+                sampling_rate = 16000,  # Hz
+                num_channels = 1,  # Mono
+                sample_width = 2,  # 16-bit audio
+                ):
+
+    # Calculate the number of samples
+    num_samples = audio_length_bytes / (num_channels * sample_width)
+
+    # Calculate the duration in seconds
+    duration_seconds = num_samples / sampling_rate
+
+    return duration_seconds
+
+
+class Microphone:
+    def __init__(self,
+            samplerate = 16000,  # Vosk models typically use a 16kHz sample rate
+            channels = 1,  # Mono audio
+            device = None,  # Default device
+            dtype = 'int16',  # Vosk models typically use 16-bit audio
+        ):
+        self.q = queue.Queue()
+        self.samplerate = samplerate
+        self.channels = channels
+        self.device = device
+        self.dtype = dtype
+
+    # Fonction callback pour traiter les morceaux audio
+    def callback(self, indata, frames, time, status):
+        if status:
+            print(status)
+        self.q.put(bytes(indata))
+        # if frames > 1000:  # Ajustez cette valeur pour essayer différents morceaux de taille
+    #     rec.AcceptWaveform(bytes(indata))
+
+
+    def open_stream(self):
+        self.q.queue.clear()
+        return sd.InputStream(samplerate=self.samplerate, device=self.device,
+                              channels=self.channels, callback=self.callback, dtype=self.dtype)
+
+    def device_info(self):
+        return sd.query_devices(self.device, 'input')
+
+    def get_duraction(self, audio_length_bytes):
+        return get_duration(audio_length_bytes, self.samplerate, self.channels, {'int16':2}[self.dtype])

scribe_cli-0.3.0/scribe/install_desktop.py

@@ -0,0 +1,43 @@
+import os, sys, platform, shutil, sysconfig
+import argparse
+
+def main():
+
+    # Check if the current platform is Linux
+    if platform.system() != "Linux":
+        print("This package is only supported on Linux systems.", file=sys.stderr)
+        sys.exit(0)
+
+    parser = argparse.ArgumentParser("Install the desktop file for the scribe package. Any arguments to this script will be passed on to `scribe`.")
+    o, rest = parser.parse_known_args()
+    o.arguments = rest
+
+    PACKAGE_NAME = 'scribe'
+
+    HOME = os.environ.get('HOME',os.path.expanduser('~'))
+    XDG_SHARE = os.environ.get('XDG_DATA_HOME', os.path.join(HOME, '.local','share'))
+    XDG_APP_DATA = os.path.join(XDG_SHARE, 'applications')
+    XDG_SCRIBE_DATA = os.path.join(XDG_SHARE, PACKAGE_NAME)
+
+
+    # Create the directory if it doesn't exist
+    os.makedirs(XDG_SCRIBE_DATA, exist_ok=True)
+    os.makedirs(XDG_APP_DATA, exist_ok=True)
+
+    # Copy your files to the desired location
+    print("Copying files to", XDG_SCRIBE_DATA)
+    shutil.copy('share/icon.jpg', XDG_SCRIBE_DATA)
+
+    with open('templates/scribe.desktop') as f:
+        template = f.read()
+
+    bin_folder = sysconfig.get_path("scripts")
+    desktop_file = template.format(XDG_SCRIBE_DATA=XDG_SCRIBE_DATA, bin_folder=bin_folder, options=' '.join(o.arguments))
+
+    print("Writing desktop file to", XDG_APP_DATA)
+    with open(os.path.join(XDG_APP_DATA, 'scribe.desktop'), "w") as f:
+        f.write(desktop_file)
+
+
+if __name__ == "__main__":
+    main()

scribe_cli-0.3.0/scribe/keyboard.py

@@ -0,0 +1,19 @@
+"""This module handles typing characters as if they were typed on a keyboard.
+"""
+try:
+    # import pyautogui
+    from pynput.keyboard import Controller
+
+except ImportError:
+    print("Please install pynput to use the keyboard feature.")
+    print("Alternatively specify [keyboard] optional dependency to voskrealtime, e.g. `pip install -e .[keyboard]`")
+    raise
+
+# Create a keyboard controller
+keyboard = Controller()
+
+def type_text(text, interval=0):
+    # Simulate typing a string
+    # import subprocess
+    # subprocess.run(["ydotool", "type", text])
+    keyboard.type(text)

scribe_cli-0.3.0/scribe/models.py

@@ -0,0 +1,133 @@
+import os
+import json
+import numpy as np
+from scribe.util import download_model
+
+VOSK_MODELS_FOLDER = os.path.join(os.environ.get("HOME"),
+                                      ".local/share/vosk/language-models")
+
+
+class AbstractTranscriber:
+    backend = None
+    def __init__(self, model, model_name=None, language=None, samplerate=16000, model_kwargs={}):
+        self.model_name = model_name
+        self.language = language
+        self.model = model
+        self.model_kwargs = model_kwargs
+        self.samplerate = samplerate
+
+    def transcribe_audio(self, audio_data):
+        raise NotImplementedError()
+
+    def transcribe_realtime_audio(self, audio_data):
+        raise NotImplementedError()
+
+    def start_recording(self, microphone,
+                        start_message="Recording... Press Ctrl+C to stop.",
+                        stop_message="Stopped recording."):
+
+        with microphone.open_stream():
+            print(start_message)
+
+            try:
+                while True:
+                    while not microphone.q.empty():
+                        data = microphone.q.get()
+                        yield self.transcribe_realtime_audio(data)
+
+            except KeyboardInterrupt:
+                pass
+
+            finally:
+                result = self.finalize()
+                microphone.q.queue.clear()
+                yield result
+
+            print(stop_message)
+
+
+def get_vosk_model(model, data_folder=None, url=None):
+    """Load the Vosk recognizer"""
+    import vosk
+    if data_folder is None:
+        data_folder = VOSK_MODELS_FOLDER
+    model_path = os.path.join(data_folder, model)
+    if not os.path.exists(model_path):
+        if url is None:
+            url = f"https://alphacephei.com/vosk/models/{model}.zip"
+        download_model(url, data_folder)
+        assert os.path.exists(model_path)
+
+    return vosk.Model(model_path)
+
+
+def get_vosk_recognizer(model, samplerate=16000):
+    import vosk
+    return vosk.KaldiRecognizer(model, samplerate)
+
+
+class VoskTranscriber(AbstractTranscriber):
+    backend = "vosk"
+
+    def __init__(self, model_name, model=None, model_kwargs={}, **kwargs):
+        if model is None:
+            model = get_vosk_model(model_name, **model_kwargs)
+        super().__init__(model, model_name, model_kwargs=model_kwargs, **kwargs)
+        self.recognizer = get_vosk_recognizer(model, self.samplerate)
+
+    def transcribe_realtime_audio(self, audio_bytes=b"", finalize=False):
+        final = self.recognizer.AcceptWaveform(audio_bytes)
+        if final:
+            result = self.recognizer.Result()
+        else:
+            result = self.recognizer.PartialResult()
+        result_dict = json.loads(result)
+
+        if final:
+            pass
+        elif finalize:
+            result_dict["text"] = result_dict.pop("partial", "")
+        else:
+            assert not final
+            if "text" in result_dict:
+                del result_dict["text"]
+        return result_dict
+
+    def transcribe_audio(self, audio_data=None):
+        return self.transcribe_realtime_audio(audio_data, finalize=True)
+
+    def finalize(self):
+        return self.transcribe_audio(b"")
+
+
+class WhisperTranscriber(AbstractTranscriber):
+    backend = "whisper"
+
+    def __init__(self, model_name, language=None, model=None, model_kwargs={}, **kwargs):
+        import whisper
+        if model is None:
+            model = whisper.load_model(model_name)
+        super().__init__(model, model_name, language, model_kwargs=model_kwargs, **kwargs)
+        self.audio_buffer = b''
+
+    def transcribe_realtime_audio(self, audio_bytes=b"", max_duration=60):
+        self.audio_buffer += audio_bytes
+
+        one_second = self.samplerate * 2 # 16-bit audio, 1 channel  ~ 32000 bytes
+        if len(self.audio_buffer) < max_duration * one_second:
+            return {"partial": f"{len(self.audio_buffer)} bytes received (duration: {len(self.audio_buffer) / one_second:.2f} seconds)"}
+
+        else:
+            return self.finalize()
+
+    def transcribe_audio(self, audio_bytes):
+        print("\nTranscribing...")
+        audio_array = np.frombuffer(audio_bytes, dtype=np.int16).flatten().astype(np.float32) / 32768.0
+        return self.model.transcribe(audio_array, fp16=False, language=self.language)
+
+    def finalize(self):
+        if len(self.audio_buffer) == 0:
+            return {"text": ""}
+        result = self.transcribe_audio(self.audio_buffer)
+        self.audio_buffer = b''
+        return result

scribe_cli-0.3.0/scribe/models.toml

@@ -0,0 +1,31 @@
+[vosk.en]
+model = "vosk-model-en-us-0.42-gigaspeech"
+
+[vosk.fr]
+model = "vosk-model-fr-0.22"
+
+[vosk.de]
+model = "vosk-model-de-tuda-0.6-900k"
+
+[vosk.it]
+model = "vosk-model-it-0.22"
+
+[_meta.en]
+language = "English (US)"
+start_message = "Listening... Press Ctrl+C to stop."
+stop_message = "Recording stopped."
+
+[_meta.fr]
+language = "French"
+start_message = "En écoute... Appuyez sur Ctrl+C pour arrêter."
+stop_message = "Écoute arrêtée."
+
+[_meta.de]
+language = "German"
+start_message = "Hören... Drücken Sie Strg+C, um zu stoppen."
+stop_message = "Aufnahme gestoppt."
+
+[_meta.it]
+language = "Italian"
+start_message = "In ascolto... Premere Ctrl+C per interrompere."
+stop_message = "Registrazione interrotta."