# Octopus Binding for Python
## Octopus
Made in Vancouver, Canada by [Picovoice](https://picovoice.ai)
Octopus is Picovoice's Speech-to-Index engine. It directly indexes speech without relying on a text representation. This
acoustic-only approach boosts accuracy by removing out-of-vocabulary limitation and eliminating the problem of competing
hypothesis (e.g. homophones)
## Compatibility
- Python 3.5+
- Runs on Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64)
## Installation
```console
pip3 install pvoctopus
```
## AccessKey
Octopus requires a valid Picovoice `AccessKey` at initialization. `AccessKey` acts as your credentials when using Octopus SDKs.
You can get your `AccessKey` for free. Make sure to keep your `AccessKey` secret.
Signup or Login to [Picovoice Console](https://console.picovoice.ai/) to get your `AccessKey`.
## Usage
Create an instance of the engine:
```python
import pvoctopus
access_key = "${ACCESS_KEY}" # AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)
octopus = pvoctopus.create(access_key=access_key)
```
Octopus consists of two steps: Indexing and Searching. Indexing transforms audio data into a `Metadata` object that
searches can be run against.
Octopus indexing has two modes of operation: indexing PCM audio data, or indexing an audio file.
When indexing PCM audio data, the valid audio sample rate is given by `handle.sample_rate`.
The engine accepts 16-bit linearly-encoded PCM and operates on single-channel audio:
```python
audio_data = [...]
metadata = octopus.index(audio_data)
```
Similarly, files can be indexed by passing in the absolute file path to the audio object.
Supported file formats are mp3, flac, wav and opus:
```python
audio_file_path = "/path/to/my/audiofile.wav"
metadata = octopus.index_file(audio_file_path)
```
Once the `Metadata` object has been created, it can be used for searching:
```python
search_term = 'picovoice'
matches = octopus.search(metadata, [search_term])
```
Multiple search terms can be given:
```python
matches = octopus.search(metadata, ['picovoice', 'Octopus', 'rhino'])
```
The `matches` object is a dictionary where the `key` is the `phrase`, and the `value` is a `list` of `Match` objects.
The `Match` object contains the `start_sec`, `end_sec` and `probability` of each match:
```python
matches = octopus.search(metadata, ['avocado'])
avocado_matches = matches['avocado']
for match in avocado_matches:
print(f"Match for `avocado`: {match.start_sec} -> {match.end_sec} ({match.probability})")
```
The `Metadata` object can be cached or stored to skip the indexing step on subsequent searches.
This can be done with the `to_bytes()` and `from_bytes()` methods:
```python
metadata_bytes = metadata.to_bytes()
# ... Write & load `metadata_bytes` from cache/filesystem/etc.
cached_metadata = pvoctopus.OctopusMetadata.from_bytes(metadata_bytes)
matches = octopus.search(cached_metadata, ['avocado'])
```
When done the Octopus, resources have to be released explicitly:
```python
octopus.delete()
```
## Non-English Models
In order to search non-English phrases you need to use the corresponding model file. The model files for all supported
languages are available [here](https://github.com/Picovoice/octopus/tree/main/lib/common/param).
## Demos
[pvoctopusdemo](https://pypi.org/project/pvoctopusdemo/) provides command-line utilities for searching audio files using
Octopus.
Raw data
{
"_id": null,
"home_page": "https://github.com/Picovoice/octopus",
"name": "pvoctopus",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "Speech-to-Index,Voice Search,Keyword Spotting,Speech Recognition,Voice Recognition",
"author": "Picovoice",
"author_email": "hello@picovoice.ai",
"download_url": "https://files.pythonhosted.org/packages/07/23/1e5bfdb00ba65f5a3e566f412bfd1ada756050d28eb957454f5a6b7c335a/pvoctopus-2.0.0.tar.gz",
"platform": null,
"description": "# Octopus Binding for Python\n\n## Octopus\n\nMade in Vancouver, Canada by [Picovoice](https://picovoice.ai)\n\nOctopus is Picovoice's Speech-to-Index engine. It directly indexes speech without relying on a text representation. This\nacoustic-only approach boosts accuracy by removing out-of-vocabulary limitation and eliminating the problem of competing\nhypothesis (e.g. homophones)\n\n## Compatibility\n\n- Python 3.5+\n- Runs on Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64)\n\n## Installation\n\n```console\npip3 install pvoctopus\n```\n\n## AccessKey\n\nOctopus requires a valid Picovoice `AccessKey` at initialization. `AccessKey` acts as your credentials when using Octopus SDKs.\nYou can get your `AccessKey` for free. Make sure to keep your `AccessKey` secret.\nSignup or Login to [Picovoice Console](https://console.picovoice.ai/) to get your `AccessKey`.\n\n## Usage\n\nCreate an instance of the engine:\n\n```python\nimport pvoctopus\n\naccess_key = \"${ACCESS_KEY}\" # AccessKey obtained from Picovoice Console (https://console.picovoice.ai/)\noctopus = pvoctopus.create(access_key=access_key)\n```\n\nOctopus consists of two steps: Indexing and Searching. Indexing transforms audio data into a `Metadata` object that\nsearches can be run against.\n\nOctopus indexing has two modes of operation: indexing PCM audio data, or indexing an audio file.\n\nWhen indexing PCM audio data, the valid audio sample rate is given by `handle.sample_rate`.\nThe engine accepts 16-bit linearly-encoded PCM and operates on single-channel audio:\n\n```python\naudio_data = [...]\nmetadata = octopus.index(audio_data)\n```\n\nSimilarly, files can be indexed by passing in the absolute file path to the audio object.\nSupported file formats are mp3, flac, wav and opus:\n\n```python\naudio_file_path = \"/path/to/my/audiofile.wav\"\nmetadata = octopus.index_file(audio_file_path)\n```\n\nOnce the `Metadata` object has been created, it can be used for searching:\n\n```python\nsearch_term = 'picovoice'\nmatches = octopus.search(metadata, [search_term])\n```\n\nMultiple search terms can be given:\n```python\nmatches = octopus.search(metadata, ['picovoice', 'Octopus', 'rhino'])\n```\n\nThe `matches` object is a dictionary where the `key` is the `phrase`, and the `value` is a `list` of `Match` objects.\nThe `Match` object contains the `start_sec`, `end_sec` and `probability` of each match:\n\n```python\nmatches = octopus.search(metadata, ['avocado'])\n\navocado_matches = matches['avocado']\nfor match in avocado_matches:\n print(f\"Match for `avocado`: {match.start_sec} -> {match.end_sec} ({match.probability})\")\n```\n\nThe `Metadata` object can be cached or stored to skip the indexing step on subsequent searches.\nThis can be done with the `to_bytes()` and `from_bytes()` methods:\n\n```python\nmetadata_bytes = metadata.to_bytes()\n\n# ... Write & load `metadata_bytes` from cache/filesystem/etc.\n\ncached_metadata = pvoctopus.OctopusMetadata.from_bytes(metadata_bytes)\nmatches = octopus.search(cached_metadata, ['avocado'])\n```\n\nWhen done the Octopus, resources have to be released explicitly:\n\n```python\noctopus.delete()\n```\n\n## Non-English Models\n\nIn order to search non-English phrases you need to use the corresponding model file. The model files for all supported\nlanguages are available [here](https://github.com/Picovoice/octopus/tree/main/lib/common/param).\n\n## Demos\n\n[pvoctopusdemo](https://pypi.org/project/pvoctopusdemo/) provides command-line utilities for searching audio files using\nOctopus.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Octopus Speech-to-Index engine.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/Picovoice/octopus"
},
"split_keywords": [
"speech-to-index",
"voice search",
"keyword spotting",
"speech recognition",
"voice recognition"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ccd353f050f79bfea4e620b4337191cebc310965e7d4ef469c1c592855126ea2",
"md5": "5d21467820ff45f0cde61453518ee389",
"sha256": "91837722cf119099dfad6b9dbde20692e40cc9affd433f9f33bdc2095a012db8"
},
"downloads": -1,
"filename": "pvoctopus-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d21467820ff45f0cde61453518ee389",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 7866569,
"upload_time": "2023-11-23T23:29:32",
"upload_time_iso_8601": "2023-11-23T23:29:32.377378Z",
"url": "https://files.pythonhosted.org/packages/cc/d3/53f050f79bfea4e620b4337191cebc310965e7d4ef469c1c592855126ea2/pvoctopus-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "07231e5bfdb00ba65f5a3e566f412bfd1ada756050d28eb957454f5a6b7c335a",
"md5": "5ed18ef379e95bd2776812d73b11dedf",
"sha256": "3ff1be7951781bb319fb8e05658b0cf3249a9988614771044a7e62dd917cb677"
},
"downloads": -1,
"filename": "pvoctopus-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5ed18ef379e95bd2776812d73b11dedf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 7863802,
"upload_time": "2023-11-23T23:29:35",
"upload_time_iso_8601": "2023-11-23T23:29:35.727762Z",
"url": "https://files.pythonhosted.org/packages/07/23/1e5bfdb00ba65f5a3e566f412bfd1ada756050d28eb957454f5a6b7c335a/pvoctopus-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-23 23:29:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Picovoice",
"github_project": "octopus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pvoctopus"
}
JSON
