# twelvelabs

A RocketRide filter node that sends a video to TwelveLabs along with instructions and returns the generated text response.

## What it does

Analyzes video using the TwelveLabs **Pegasus** model (`pegasus1.2`, with both `visual` and `audio` model options) and emits the generated text. For each incoming video stream the node:

1. Buffers the video chunks in memory and writes them to a temporary file when the stream ends.
2. Creates a temporary TwelveLabs index named `rocketride-<random>`.
3. Uploads the video as an indexing task and polls every 5 seconds until the task is `ready` (raises an error if the task reports `failed`, or after a **15-minute timeout**).
4. Calls the TwelveLabs analyze endpoint with your configured instructions as the prompt and writes the result to the `text` lane.
5. Deletes the temporary index and the temporary file, even on failure.

Uses the official **`twelvelabs`** Python SDK. If no instructions are configured, the prompt defaults to `Describe this video.`. If TwelveLabs returns an empty result, the node outputs the string `No data from TwelveLabs`.

Supported input formats (by MIME type): MP4, MOV (QuickTime), AVI, WebM, MKV, and MPG. Unrecognized video MIME types are written to a `.mp4` temp file before upload.

---

## Configuration

### Lanes

| Lane in | Lane out | Description                          |
| ------- | -------- | ------------------------------------ |
| `video` | `text`   | Analyze video and return text output |

The text result is only emitted when a downstream node is listening on the `text` lane.

### Fields

| Field | Type | Description |
|---|---|---|
| `apikey` | string | TwelveLabs API key. |
| `instructions` | array | Instructions to guide TwelveLabs when analyzing the video. |
| `profile` | string | Default "default".  |

The node ships a single `default` profile containing both fields.

---

## Authentication

Provide your TwelveLabs API key in the `apikey` field. The key is loaded once when the pipeline starts and shared by all instances of the node. Get a key from the [TwelveLabs dashboard](https://docs.twelvelabs.io).

---

## Operational notes

- Each video processed creates and then deletes its own TwelveLabs index, no persistent index is reused, so nothing accumulates in your TwelveLabs account, but indexing happens from scratch on every video.
- Indexing time depends on video length; tasks that take longer than 15 minutes raise `TwelveLabs task timed out`.
- Videos are currently buffered fully in memory before being written to the temp file, so very large videos increase memory usage accordingly.

---

## Upstream docs

- [TwelveLabs documentation](https://docs.twelvelabs.io)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `twelvelabs.apikey` | `string` | **API Key**<br/>TwelveLabs API key. |  |
| `twelvelabs.instructions` | `array` | **Instructions**<br/>Instructions to guide TwelveLabs when analyzing the video. |  |
| `twelvelabs.profile` | `string` |  | `"default"` |

## Dependencies

- `twelvelabs`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/twelvelabs)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->