# Python Furhat WebSocket API Client
Python implementation of Furhat WebSocket API client.
There are two different clients:
- `FurhatClient`: A synchronous (blocking) client for simple, sequential command execution.
- `AsyncFurhatClient`: An asynchronous client for advanced, concurrent, or event-driven interactions.
## Installation
Install the module with pip:
```
pip install furhat-ws-api
```
Then include it your code:
```python
from furhat_ws_api import *
```
## Synchronous Event client
The synchronous client (`FurhatClient`) is a wrapper around the asynchronous client that allows for blocking calls in a standard (non-async) Python context. This is useful for simple use cases where you want to send one command at a time and wait for the result before proceeding. Note that it is not suitable for advanced scenarios requiring concurrent or overlapping commands.
```python
from furhat_ws_api import FurhatClient
import logging
furhat = FurhatClient("127.0.0.1") # Add authentication key as second argument if needed
furhat.set_logging_level(logging.INFO) # Use logging.DEBUG for more details
furhat.connect()
furhat.request_speak_text("Hello world, I am Furhat.")
furhat.disconnect()
```
## Asyncronous Event client
The asynchronous client is based on the Python [asyncio](https://docs.python.org/3/library/asyncio.html) library. This allows for much more flexible use cases, where requests can be aborted and responses can be streamed while actions are being executed.
```python
from furhat_ws_api import AsyncFurhatClient
import asyncio
import logging
furhat = AsyncFurhatClient("127.0.0.1")
async def run_example():
await furhat.connect()
await furhat.request_speak_text("Hello world, I am Furhat.", wait=True)
await furhat.disconnect()
asyncio.run(run_example())
```
Note that one important difference when making requests in the asynchronous API is that they need to be called with the `await` keyword.
If you want to mix the use of the synchronous and asynchronous clients, you should not instantiate both, but you can access it like this:
```python
from furhat_ws_api import FurhatClient
import logging
furhat = FurhatClient("127.0.0.1")
furhat_async = furhat.async_client
furhat.connect()
async def run_example():
await furhat_async.speak_text("Hello world, I am Furhat.", wait=True)
asyncio.run(run_example())
```
### Reacting to events
With the asynchronous client, you can react to events from Furhat. This allows your application to react to specific events from the Furhat robot, such as when the robot starts or stops speaking, hears something, or detects a user.
Here is an example of how to react to events related to Furhat speaking:
```python
from furhat_ws_api import AsyncFurhatClient, Events
import asyncio
furhat = AsyncFurhatClient("127.0.0.1")
async def on_speak_start(event):
print("Furhat started speaking:", event)
async def on_speak_end(event):
print("Furhat finished speaking:", event)
async def main():
await furhat.connect()
# Register handlers
furhat.add_handler(Events.response_speak_start, on_speak_start)
furhat.add_handler(Events.response_speak_end, on_speak_end)
await furhat.request_speak_text("Hello! Please say something.")
await furhat.disconnect()
asyncio.run(main())
```
## Supported methods
Here is a summary of the main methods. All of them are available in the asynchronous API, but only some of them in the synchronous wrapper API.
- `connect()` / `disconnect()`
- Establishes or closes the connection to the Furhat robot.
### Speaking
- `request_speak_text(text: str, wait: bool = True, abort: bool = True)`
- Makes Furhat speak the given text. If `wait` is True, the method blocks until speaking is finished. If `abort` is True, any ongoing speech is stopped before starting the new one.
- `request_speak_audio(url: str, wait: bool = True, abort: bool = True, text: str, lipsync: bool = True)`
- Makes Furhat play the given audio (from url). Same `wait` and `abort` logic as `speak_text`. `text` is just for logging purposes and can be omitted. `lipsync` denotes whether automatic lipsync should be added.
- `request_speak_stop()`
- Immediately stops any ongoing speech or audio playback.
You can add the following events handlers:
- `response_speak_start`
- Furhat starts speaking
- `response_speak_end`
- Furhat stops speaking
### Listening (for speech)
- `request_listen()`
- Starts listening for user speech and returns the recognized text. Blocks until the listening interaction is complete.
### Voice
- `request_voice_status()`
- Returns the current voice configuration and status of the robot.
- `request_voice_config(voice_id: str, language: str, provider: str, gender: str, name: str)`
- Changes the robot's voice according to the parameters (one or several can be used to add constraints).
### Attention
- `request_attend_user(user_id: str)`
- Makes Furhat turn its attention to a specific user (by user ID). Use the string `closest` to attend to the closest user.
- `request_attend_location(x: float, y: float, z: float)`
- Makes Furhat attend to a specific location.
### Gestures
- `request_gesture(gesture_name: str, intensity: float = 1.0, duration: float = 1.0, wait: bool = False)`
- Makes Furhat perform a gesture. You can control the intensity and duration. If `wait` is True, the method blocks until the gesture is finished.
### Face
- `request_face_params(params_dict: dict)`
- Sets facial animation parameters directly. The `params_dict` should specify the desired facial features and their values.
- `request_face_headpose(yaw: float, pitch: float, roll: float, relative: bool)`
- Directly controls the head pose of the robot. Set `relative` to True for movement relative to current gaze (attention) target, or False for absolute positioning.
- `request_face_config(face_id: str, visibility: bool = True, microexpressions: bool = True)`
- Sets the current mask and character (face), and/or face visibility and microexpressions.
- `request_face_status(face_id: bool = True, face_list: bool = True)`
- Gets the current and available masks and characters. Returns information about the face configuration.
- `request_face_reset()`
- Resets all facial parameters to their default values.
### LED
- `request_led_set(color: str)`
- Sets the color of the robot's LED. The `color` can be a color name (e.g., "red") or a hex code (e.g., "#FF0000").
Raw data
{
"_id": null,
"home_page": null,
"name": "furhat-ws-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "api, client, furhat, robotics, websocket",
"author": null,
"author_email": "Your Name <you@example.com>",
"download_url": "https://files.pythonhosted.org/packages/a6/39/03b14df928040eb9170c8bf180ee4cf02ca5c51a636ced13870d6234cd5d/furhat_ws_api-0.1.1.tar.gz",
"platform": null,
"description": "# Python Furhat WebSocket API Client\n\nPython implementation of Furhat WebSocket API client. \n\nThere are two different clients:\n\n- `FurhatClient`: A synchronous (blocking) client for simple, sequential command execution.\n- `AsyncFurhatClient`: An asynchronous client for advanced, concurrent, or event-driven interactions.\n\n## Installation\n\nInstall the module with pip:\n\n```\npip install furhat-ws-api\n```\n\nThen include it your code:\n\n```python\nfrom furhat_ws_api import *\n```\n\n## Synchronous Event client\n\nThe synchronous client (`FurhatClient`) is a wrapper around the asynchronous client that allows for blocking calls in a standard (non-async) Python context. This is useful for simple use cases where you want to send one command at a time and wait for the result before proceeding. Note that it is not suitable for advanced scenarios requiring concurrent or overlapping commands.\n\n```python\nfrom furhat_ws_api import FurhatClient\nimport logging\n\nfurhat = FurhatClient(\"127.0.0.1\") # Add authentication key as second argument if needed\nfurhat.set_logging_level(logging.INFO) # Use logging.DEBUG for more details\nfurhat.connect()\nfurhat.request_speak_text(\"Hello world, I am Furhat.\")\nfurhat.disconnect()\n```\n\n## Asyncronous Event client\n\nThe asynchronous client is based on the Python [asyncio](https://docs.python.org/3/library/asyncio.html) library. This allows for much more flexible use cases, where requests can be aborted and responses can be streamed while actions are being executed. \n\n```python\nfrom furhat_ws_api import AsyncFurhatClient\nimport asyncio\nimport logging\n\nfurhat = AsyncFurhatClient(\"127.0.0.1\")\n\nasync def run_example():\n await furhat.connect()\n await furhat.request_speak_text(\"Hello world, I am Furhat.\", wait=True)\n await furhat.disconnect()\n\nasyncio.run(run_example())\n```\n\nNote that one important difference when making requests in the asynchronous API is that they need to be called with the `await` keyword.\n\nIf you want to mix the use of the synchronous and asynchronous clients, you should not instantiate both, but you can access it like this:\n\n```python\nfrom furhat_ws_api import FurhatClient\nimport logging\n\nfurhat = FurhatClient(\"127.0.0.1\") \nfurhat_async = furhat.async_client\nfurhat.connect()\n\nasync def run_example():\n await furhat_async.speak_text(\"Hello world, I am Furhat.\", wait=True)\n\nasyncio.run(run_example())\n```\n\n### Reacting to events\n\nWith the asynchronous client, you can react to events from Furhat. This allows your application to react to specific events from the Furhat robot, such as when the robot starts or stops speaking, hears something, or detects a user.\n\nHere is an example of how to react to events related to Furhat speaking:\n\n```python\nfrom furhat_ws_api import AsyncFurhatClient, Events\nimport asyncio\n\nfurhat = AsyncFurhatClient(\"127.0.0.1\")\n\nasync def on_speak_start(event):\n print(\"Furhat started speaking:\", event)\n\nasync def on_speak_end(event):\n print(\"Furhat finished speaking:\", event)\n\nasync def main():\n await furhat.connect()\n # Register handlers\n furhat.add_handler(Events.response_speak_start, on_speak_start)\n furhat.add_handler(Events.response_speak_end, on_speak_end)\n \n await furhat.request_speak_text(\"Hello! Please say something.\")\n await furhat.disconnect()\n\nasyncio.run(main())\n```\n\n## Supported methods\n\nHere is a summary of the main methods. All of them are available in the asynchronous API, but only some of them in the synchronous wrapper API. \n\n- `connect()` / `disconnect()`\n - Establishes or closes the connection to the Furhat robot.\n\n### Speaking\n\n- `request_speak_text(text: str, wait: bool = True, abort: bool = True)`\n - Makes Furhat speak the given text. If `wait` is True, the method blocks until speaking is finished. If `abort` is True, any ongoing speech is stopped before starting the new one.\n\n- `request_speak_audio(url: str, wait: bool = True, abort: bool = True, text: str, lipsync: bool = True)`\n - Makes Furhat play the given audio (from url). Same `wait` and `abort` logic as `speak_text`. `text` is just for logging purposes and can be omitted. `lipsync` denotes whether automatic lipsync should be added.\n\n- `request_speak_stop()`\n - Immediately stops any ongoing speech or audio playback.\n\nYou can add the following events handlers:\n\n- `response_speak_start`\n - Furhat starts speaking\n\n- `response_speak_end` \n - Furhat stops speaking\n\n### Listening (for speech)\n\n- `request_listen()`\n - Starts listening for user speech and returns the recognized text. Blocks until the listening interaction is complete.\n\n### Voice \n\n- `request_voice_status()`\n - Returns the current voice configuration and status of the robot.\n\n- `request_voice_config(voice_id: str, language: str, provider: str, gender: str, name: str)`\n - Changes the robot's voice according to the parameters (one or several can be used to add constraints).\n\n### Attention\n\n- `request_attend_user(user_id: str)`\n - Makes Furhat turn its attention to a specific user (by user ID). Use the string `closest` to attend to the closest user. \n\n- `request_attend_location(x: float, y: float, z: float)`\n - Makes Furhat attend to a specific location.\n\n### Gestures \n\n- `request_gesture(gesture_name: str, intensity: float = 1.0, duration: float = 1.0, wait: bool = False)`\n - Makes Furhat perform a gesture. You can control the intensity and duration. If `wait` is True, the method blocks until the gesture is finished.\n\n### Face \n\n- `request_face_params(params_dict: dict)`\n - Sets facial animation parameters directly. The `params_dict` should specify the desired facial features and their values.\n\n- `request_face_headpose(yaw: float, pitch: float, roll: float, relative: bool)`\n - Directly controls the head pose of the robot. Set `relative` to True for movement relative to current gaze (attention) target, or False for absolute positioning.\n\n- `request_face_config(face_id: str, visibility: bool = True, microexpressions: bool = True)`\n - Sets the current mask and character (face), and/or face visibility and microexpressions.\n\n- `request_face_status(face_id: bool = True, face_list: bool = True)`\n - Gets the current and available masks and characters. Returns information about the face configuration.\n\n- `request_face_reset()`\n - Resets all facial parameters to their default values.\n\n### LED \n\n- `request_led_set(color: str)`\n - Sets the color of the robot's LED. The `color` can be a color name (e.g., \"red\") or a hex code (e.g., \"#FF0000\").\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client for the Furhat WebSocket API.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://docs.furhat.io/"
},
"split_keywords": [
"api",
" client",
" furhat",
" robotics",
" websocket"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2cedbe9b4ecaf7f4abb05e1d4f15ff902b1bddb4018616ccf8cc6030d78e60d9",
"md5": "8a9e44d4fa071896bf9206a60cba58bf",
"sha256": "9508952c06347a76f2cd4236f54492dc4bfc43d5b66b28ae27ca862cc67f733e"
},
"downloads": -1,
"filename": "furhat_ws_api-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8a9e44d4fa071896bf9206a60cba58bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9784,
"upload_time": "2025-09-01T12:45:02",
"upload_time_iso_8601": "2025-09-01T12:45:02.845386Z",
"url": "https://files.pythonhosted.org/packages/2c/ed/be9b4ecaf7f4abb05e1d4f15ff902b1bddb4018616ccf8cc6030d78e60d9/furhat_ws_api-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a63903b14df928040eb9170c8bf180ee4cf02ca5c51a636ced13870d6234cd5d",
"md5": "0eca8ff1a2a0ac08099a26b0d2681859",
"sha256": "809c6a9ec3695bc8d16549b90001360358908eefdf95a2b54c4221c74367eb0e"
},
"downloads": -1,
"filename": "furhat_ws_api-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "0eca8ff1a2a0ac08099a26b0d2681859",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8041,
"upload_time": "2025-09-01T12:45:04",
"upload_time_iso_8601": "2025-09-01T12:45:04.245554Z",
"url": "https://files.pythonhosted.org/packages/a6/39/03b14df928040eb9170c8bf180ee4cf02ca5c51a636ced13870d6234cd5d/furhat_ws_api-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 12:45:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "furhat-ws-api"
}
JSON