==========
whispercpp
==========
*Pybind11 bindings for* `whisper.cpp <https://github.com/ggerganov/whisper.cpp.git>`_
Quickstart
~~~~~~~~~~
Install with pip:
.. code-block:: bash
pip install whispercpp
To use the latest version, install from source:
.. code-block:: bash
pip install git+https://github.com/aarnphm/whispercpp.git
For local setup, initialize all submodules:
.. code-block:: bash
git submodule update --init --recursive
Build the wheel:
.. code-block:: bash
# Option 1: using pypa/build
python3 -m build -w
# Option 2: using bazel
./tools/bazel build //:whispercpp_wheel
Install the wheel:
.. code-block:: bash
# Option 1: via pypa/build
pip install dist/*.whl
# Option 2: using bazel
pip install $(./tools/bazel info bazel-bin)/*.whl
The binding provides a ``Whisper`` class:
.. code-block:: python
from whispercpp import Whisper
w = Whisper.from_pretrained("tiny.en")
Currently, the inference API is provided via ``transcribe``:
.. code-block:: python
w.transcribe(np.ones((1, 16000)))
You can use `ffmpeg <https://github.com/kkroening/ffmpeg-python>`_ or `librosa <https://librosa.org/doc/main/index.html>`_
to load audio files into a Numpy array, then pass it to ``transcribe``:
.. code-block:: python
import ffmpeg
import numpy as np
try:
y, _ = (
ffmpeg.input("/path/to/audio.wav", threads=0)
.output("-", format="s16le", acodec="pcm_s16le", ac=1, ar=sample_rate)
.run(
cmd=["ffmpeg", "-nostdin"], capture_stdout=True, capture_stderr=True
)
)
except ffmpeg.Error as e:
raise RuntimeError(f"Failed to load audio: {e.stderr.decode()}") from e
arr = np.frombuffer(y, np.int16).flatten().astype(np.float32) / 32768.0
w.transcribe(arr)
The Pybind11 bindings supports all of the features from whisper.cpp.
The binding can also be used via ``api``:
.. code-block:: python
from whispercpp import api
ctx = api.Context.from_file("/path/to/saved_weight.bin")
params = api.Params()
ctx.full(arr, params)
Development
~~~~~~~~~~~
See `DEVELOPMENT.md <https://github.com/aarnphm/whispercpp/blob/main/DEVELOPMENT.md>`_
APIs
~~~~
``Whisper``
------------
1. ``Whisper.from_pretrained(model_name: str) -> Whisper``
Load a pre-trained model from the local cache or download and cache if needed.
.. code-block:: python
w = Whisper.from_pretrained("tiny.en")
The model will be saved to ``$XDG_DATA_HOME/whispercpp`` or ``~/.local/share/whispercpp`` if the environment variable is
not set.
2. ``Whisper.transcribe(arr: NDArray[np.float32], num_proc: int = 1)``
Running transcription on a given Numpy array. This calls ``full`` from ``whisper.cpp``. If ``num_proc`` is greater than 1,
it will use ``full_parallel`` instead.
.. code-block:: python
w.transcribe(np.ones((1, 16000)))
``api``
-------
``api`` is a direct binding from ``whisper.cpp``, that has similar APIs to `whisper-rs <https://github.com/tazz4843/whisper-rs>`_.
1. ``api.Context``
This class is a wrapper around ``whisper_context``
.. code-block:: python
from whispercpp import api
ctx = api.Context.from_file("/path/to/saved_weight.bin")
.. note::
The context can also be accessed from the ``Whisper`` class via ``w.context``
2. ``api.Params``
This class is a wrapper around ``whisper_params``
.. code-block:: python
from whispercpp import api
params = api.Params()
.. note::
The params can also be accessed from the ``Whisper`` class via ``w.params``
Why not?
~~~~~~~~
* `whispercpp.py <https://github.com/stlukey/whispercpp.py>`_. There are a few key differences here:
* They provides the Cython bindings. From the UX standpoint, this achieves the same goal as ``whispercpp``. The difference is ``whispercpp`` use Pybind11 instead. Feel free to use it if you prefer Cython over Pybind11. Note that ``whispercpp.py`` and ``whispercpp`` are mutually exclusive, as they also use the ``whispercpp`` namespace.
* ``whispercpp`` doesn't pollute your ``$HOME`` directory, rather it follows the `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_ for saved weights.
* Using ``cdll`` and ``ctypes`` and be done with it?
* This is also valid, but requires a lot of hacking and it is pretty slow comparing to Cython and Pybind11.
Raw data
{
"_id": null,
"home_page": "https://github.com/aarnphm/whispercpp",
"name": "whispercpp",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Aaron Pham",
"author_email": "aarnphm@bentoml.com",
"download_url": "https://files.pythonhosted.org/packages/2d/9b/690f807441baa32e5165ddadb31a6716549c71d2f91eb62e74dda394dffd/whispercpp-0.0.17.tar.gz",
"platform": null,
"description": "==========\nwhispercpp\n==========\n\n*Pybind11 bindings for* `whisper.cpp <https://github.com/ggerganov/whisper.cpp.git>`_\n\nQuickstart\n~~~~~~~~~~\n\nInstall with pip:\n\n.. code-block:: bash\n\n pip install whispercpp\n\nTo use the latest version, install from source:\n\n.. code-block:: bash\n\n pip install git+https://github.com/aarnphm/whispercpp.git\n\nFor local setup, initialize all submodules:\n\n.. code-block:: bash\n\n git submodule update --init --recursive\n\nBuild the wheel:\n\n.. code-block:: bash\n\n # Option 1: using pypa/build\n python3 -m build -w\n\n # Option 2: using bazel\n ./tools/bazel build //:whispercpp_wheel\n\nInstall the wheel:\n\n.. code-block:: bash\n\n # Option 1: via pypa/build\n pip install dist/*.whl\n\n # Option 2: using bazel\n pip install $(./tools/bazel info bazel-bin)/*.whl\n\nThe binding provides a ``Whisper`` class:\n\n.. code-block:: python\n\n from whispercpp import Whisper\n\n w = Whisper.from_pretrained(\"tiny.en\")\n\nCurrently, the inference API is provided via ``transcribe``:\n\n.. code-block:: python\n\n w.transcribe(np.ones((1, 16000)))\n\nYou can use `ffmpeg <https://github.com/kkroening/ffmpeg-python>`_ or `librosa <https://librosa.org/doc/main/index.html>`_\nto load audio files into a Numpy array, then pass it to ``transcribe``:\n\n.. code-block:: python\n\n import ffmpeg\n import numpy as np\n\n try:\n y, _ = (\n ffmpeg.input(\"/path/to/audio.wav\", threads=0)\n .output(\"-\", format=\"s16le\", acodec=\"pcm_s16le\", ac=1, ar=sample_rate)\n .run(\n cmd=[\"ffmpeg\", \"-nostdin\"], capture_stdout=True, capture_stderr=True\n )\n )\n except ffmpeg.Error as e:\n raise RuntimeError(f\"Failed to load audio: {e.stderr.decode()}\") from e\n\n arr = np.frombuffer(y, np.int16).flatten().astype(np.float32) / 32768.0\n\n w.transcribe(arr)\n\nThe Pybind11 bindings supports all of the features from whisper.cpp.\n\nThe binding can also be used via ``api``:\n\n.. code-block:: python\n\n from whispercpp import api\n\n ctx = api.Context.from_file(\"/path/to/saved_weight.bin\")\n params = api.Params()\n\n ctx.full(arr, params)\n\nDevelopment\n~~~~~~~~~~~\n\nSee `DEVELOPMENT.md <https://github.com/aarnphm/whispercpp/blob/main/DEVELOPMENT.md>`_\n\nAPIs\n~~~~\n\n``Whisper``\n------------\n\n1. ``Whisper.from_pretrained(model_name: str) -> Whisper``\n\n Load a pre-trained model from the local cache or download and cache if needed.\n\n .. code-block:: python\n\n w = Whisper.from_pretrained(\"tiny.en\")\n\nThe model will be saved to ``$XDG_DATA_HOME/whispercpp`` or ``~/.local/share/whispercpp`` if the environment variable is\nnot set.\n\n2. ``Whisper.transcribe(arr: NDArray[np.float32], num_proc: int = 1)``\n\n Running transcription on a given Numpy array. This calls ``full`` from ``whisper.cpp``. If ``num_proc`` is greater than 1,\n it will use ``full_parallel`` instead.\n\n .. code-block:: python\n\n w.transcribe(np.ones((1, 16000)))\n\n``api``\n-------\n\n``api`` is a direct binding from ``whisper.cpp``, that has similar APIs to `whisper-rs <https://github.com/tazz4843/whisper-rs>`_.\n\n1. ``api.Context``\n\n This class is a wrapper around ``whisper_context``\n\n .. code-block:: python\n\n from whispercpp import api\n\n ctx = api.Context.from_file(\"/path/to/saved_weight.bin\")\n\n .. note::\n\n The context can also be accessed from the ``Whisper`` class via ``w.context``\n\n2. ``api.Params``\n\n This class is a wrapper around ``whisper_params``\n\n .. code-block:: python\n\n from whispercpp import api\n\n params = api.Params()\n\n .. note::\n\n The params can also be accessed from the ``Whisper`` class via ``w.params``\n\nWhy not?\n~~~~~~~~\n\n* `whispercpp.py <https://github.com/stlukey/whispercpp.py>`_. There are a few key differences here:\n\n * They provides the Cython bindings. From the UX standpoint, this achieves the same goal as ``whispercpp``. The difference is ``whispercpp`` use Pybind11 instead. Feel free to use it if you prefer Cython over Pybind11. Note that ``whispercpp.py`` and ``whispercpp`` are mutually exclusive, as they also use the ``whispercpp`` namespace.\n\n * ``whispercpp`` doesn't pollute your ``$HOME`` directory, rather it follows the `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_ for saved weights.\n\n* Using ``cdll`` and ``ctypes`` and be done with it?\n\n * This is also valid, but requires a lot of hacking and it is pretty slow comparing to Cython and Pybind11.\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "",
"version": "0.0.17",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c939f5c52bb2c61a7a399e06821da0e71d2c14e924f1efc8503b1cb2e469ab7a",
"md5": "bf549ba8d9fc29909227e8b8dcc84558",
"sha256": "70053d9e789e270931ebd1c69a2d17504f87cec29c27187bb92f16af965a9644"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp310-cp310-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "bf549ba8d9fc29909227e8b8dcc84558",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": null,
"size": 1328998,
"upload_time": "2023-03-22T03:19:40",
"upload_time_iso_8601": "2023-03-22T03:19:40.653201Z",
"url": "https://files.pythonhosted.org/packages/c9/39/f5c52bb2c61a7a399e06821da0e71d2c14e924f1efc8503b1cb2e469ab7a/whispercpp-0.0.17-cp310-cp310-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4996557e160fc49d1c242f9423b614b5f2d1122146adc569cf068360193db5ce",
"md5": "be70d77307846e12cbb84246389b94ec",
"sha256": "91c2ceded37a4c0cb19e0f971126c2cd57d307a90cf2099ab5ec272033bcd12c"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp310-cp310-manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "be70d77307846e12cbb84246389b94ec",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": null,
"size": 1415407,
"upload_time": "2023-03-22T03:11:06",
"upload_time_iso_8601": "2023-03-22T03:11:06.383675Z",
"url": "https://files.pythonhosted.org/packages/49/96/557e160fc49d1c242f9423b614b5f2d1122146adc569cf068360193db5ce/whispercpp-0.0.17-cp310-cp310-manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69114aea56130fe2291e727d6a35e28aac27b6c8361dc087b645e162b614ecd9",
"md5": "8d45225f172964da6dcd67821a80a16d",
"sha256": "23c766b3d59026874f1e2de53c7003c26c020b1a515bdef6ea70fae5319e1baf"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp311-cp311-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "8d45225f172964da6dcd67821a80a16d",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": null,
"size": 1329845,
"upload_time": "2023-03-22T03:21:28",
"upload_time_iso_8601": "2023-03-22T03:21:28.701771Z",
"url": "https://files.pythonhosted.org/packages/69/11/4aea56130fe2291e727d6a35e28aac27b6c8361dc087b645e162b614ecd9/whispercpp-0.0.17-cp311-cp311-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d942ad80b416d2be6a500a10de8868855957de266b0906f8da23a37fa35277cb",
"md5": "df6304a3dd086413fa0c09de84f495f0",
"sha256": "2f1709e0ce7eb7cd61d9b0ae3adfde725325efced0fe08f7aa98eaf4d3d57a7f"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp311-cp311-manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "df6304a3dd086413fa0c09de84f495f0",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": null,
"size": 1480981,
"upload_time": "2023-03-22T03:10:11",
"upload_time_iso_8601": "2023-03-22T03:10:11.501571Z",
"url": "https://files.pythonhosted.org/packages/d9/42/ad80b416d2be6a500a10de8868855957de266b0906f8da23a37fa35277cb/whispercpp-0.0.17-cp311-cp311-manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5f22fe910a51bd70479a92b0e75bfaf241c38b9f644ea71b004e1b6e6148c88a",
"md5": "542bcb164a25858c0a9f91dbc7fb2a2c",
"sha256": "942266c77c6400f159443d16b73785f1f03d40026d3c821d69e8111de1165d39"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp38-cp38-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "542bcb164a25858c0a9f91dbc7fb2a2c",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": null,
"size": 1328487,
"upload_time": "2023-03-22T03:19:27",
"upload_time_iso_8601": "2023-03-22T03:19:27.243470Z",
"url": "https://files.pythonhosted.org/packages/5f/22/fe910a51bd70479a92b0e75bfaf241c38b9f644ea71b004e1b6e6148c88a/whispercpp-0.0.17-cp38-cp38-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3aab51b0c557cc5f84e409a8e05186cd6a843db712513889793651ef34c8320b",
"md5": "e3891f5ab1d35b03ae7edff64384780c",
"sha256": "6d244421c8124fc75e09def87b8f003b6597007fc76f9892a5ecdec5f32dbd55"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp38-cp38-manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "e3891f5ab1d35b03ae7edff64384780c",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": null,
"size": 1414614,
"upload_time": "2023-03-22T03:10:57",
"upload_time_iso_8601": "2023-03-22T03:10:57.248342Z",
"url": "https://files.pythonhosted.org/packages/3a/ab/51b0c557cc5f84e409a8e05186cd6a843db712513889793651ef34c8320b/whispercpp-0.0.17-cp38-cp38-manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d85f8efb9bbe31ad4121c3c648b98171ed4c32dd7c50180dc1e795d60931e83",
"md5": "98d69d9757fc5ff42fa2311654fcc5ff",
"sha256": "280bfbc83f9e516b172f15680d5e8aa52b2b7607bf2effb1e17a6b0cf1c81f38"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp39-cp39-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "98d69d9757fc5ff42fa2311654fcc5ff",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": null,
"size": 1329255,
"upload_time": "2023-03-22T03:31:13",
"upload_time_iso_8601": "2023-03-22T03:31:13.163496Z",
"url": "https://files.pythonhosted.org/packages/8d/85/f8efb9bbe31ad4121c3c648b98171ed4c32dd7c50180dc1e795d60931e83/whispercpp-0.0.17-cp39-cp39-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0be569040cca15b1867c75c997e61394a21a995b6299fa464b8f9a36724f9263",
"md5": "3ff6f47e5df1c70d277115d6b802795e",
"sha256": "12b8ce6d3e7ecbd80b677fa8732628030e9e42627205474876ebe768622f2c53"
},
"downloads": -1,
"filename": "whispercpp-0.0.17-cp39-cp39-manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "3ff6f47e5df1c70d277115d6b802795e",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": null,
"size": 1415284,
"upload_time": "2023-03-22T03:11:43",
"upload_time_iso_8601": "2023-03-22T03:11:43.420057Z",
"url": "https://files.pythonhosted.org/packages/0b/e5/69040cca15b1867c75c997e61394a21a995b6299fa464b8f9a36724f9263/whispercpp-0.0.17-cp39-cp39-manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2d9b690f807441baa32e5165ddadb31a6716549c71d2f91eb62e74dda394dffd",
"md5": "df45cbdaf685de43cd0d77eb4bd8e7d3",
"sha256": "174a2c82e0ee7bcc4c21301633df86d7de49395d81d9455a9bedfb0c790813de"
},
"downloads": -1,
"filename": "whispercpp-0.0.17.tar.gz",
"has_sig": false,
"md5_digest": "df45cbdaf685de43cd0d77eb4bd8e7d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3993701,
"upload_time": "2023-03-22T03:33:24",
"upload_time_iso_8601": "2023-03-22T03:33:24.056146Z",
"url": "https://files.pythonhosted.org/packages/2d/9b/690f807441baa32e5165ddadb31a6716549c71d2f91eb62e74dda394dffd/whispercpp-0.0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-22 03:33:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "aarnphm",
"github_project": "whispercpp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "whispercpp"
}
JSON
