Streaming API Tutorial

Overview

The streaming API is build for analysis of audio, video, and text streams. By connecting to WebSocket endpoints you can get near real-time feedback on the expressive and emotional content of your data.

If you haven't already, grab your API key using the instructions in the Get Started guide.

Streaming text with the Hume Python SDK

If you're a Python user then you're in the right place. You can also go directly to the Python SDK documentation for more examples.

To set up a connection with your own client, skip ahead to the section below!

import asyncio

from hume import HumeStreamClient
from hume.models.config import LanguageConfig

samples = [
    "Mary had a little lamb,",
    "Its fleece was white as snow."
    "Everywhere the child went,"
    "The little lamb was sure to go."
]

async def main():
    client = HumeStreamClient("<your-api-key>")
    config = LanguageConfig()
    async with client.connect([config]) as socket:
        for sample in samples:
            result = await socket.send_text(sample)
            emotions = result["language"]["predictions"][0]["emotions"]
            print(emotions)

asyncio.run(main())

Streaming with your own WebSockets client

To call the Streaming API from your own WebSockets client you'll need the API endpoint, a JSON message, and an API key header/param.

More information can be found in the streaming API reference.

To get started, you can use a WebSocket client of your choice to connect to the models endpoint:

wss://api.hume.ai/v0/stream/models

Make sure you configure the socket connection headers with your personal API key

X-Hume-Api-Key: <YOUR-API-KEY>

📘
The default WebSockets implementation in your browser may not have support for headers. If that's the case you can set the apikey query parameter.

And finally, send the following JSON message on the socket:

{
    "models": {
        "language": {}
    },
    "raw_text": true,
    "data": "Mary had a little lamb"
}

You should receive a JSON response that looks something like this:

{
  "language": {
    "predictions": [
      {
        "text": "Mary",
        "position": { "begin": 0, "end": 4 },
        "emotions": [
          { "name": "Anger", "score": 0.012025930918753147 },
          { "name": "Joy", "score": 0.056471485644578934 },
          { "name": "Sadness", "score": 0.031556881964206696 },
        ]
      },
      {
        "text": "had",
        "position": { "begin": 5, "end": 8 },
        "emotions": [
          { "name": "Anger", "score": 0.0016927534015849233 },
          { "name": "Joy", "score": 0.02388327568769455 },
          { "name": "Sadness", "score": 0.018137391656637192 },
          ...
        ]
      },
      ...
    ]
  }
}

Data Encoding

For media files like images and audio, the Streaming API requires that you base64 encode your media before sending it over a WebSocket connection.

Here's a quick example of encoding data in Python:

import base64
from pathlib import Path

def encode_data(filepath: Path) -> str:
    with Path(filepath).open('rb') as fp:
        bytes_data = base64.b64encode(fp.read())
        encoded_data = bytes_data.decode("utf-8")
        return encoded_data

filepath = "<path-to-your-media>"
encoded_data = encode_data(filepath)
print(encoded_data)

You can also use an online converter to do this step.

Overview

Streaming text with the Hume Python SDK

Streaming with your own WebSockets client

📘The default WebSockets implementation in your browser may not have support for headers. If that's the case you can set the apikey query parameter.

Data Encoding

📘
The default WebSockets implementation in your browser may not have support for headers. If that's the case you can set the `apikey` query parameter.