npm package: @pbvision/partner-sdk
Description: SDK for interacting with the PB Vision pickleball AI engine.
Latest version: 0.1.13

# PB Vision Partner Documentation <!-- omit in toc -->

The easiest way to use the PB Vision AI Engine is to simply share a link to
your video file. Our AI usually works on each video for about 30 minutes for a
standard length game, so we'll notify your servers when the results are ready.

- [Installation](#installation)
  - [Step 1: Get API Access](#step-1-get-api-access)
  - [Step 2: SDK Setup](#step-2-sdk-setup)
- [Using the API](#using-the-api)
  - [Webhook Setup](#webhook-setup)
  - [Send Videos](#send-videos)
    - [Option 1: PBV downloads your video from a URL](#option-1-pbv-downloads-your-video-from-a-url)
    - [Option 2: Upload your video](#option-2-upload-your-video)
  - [Video Editors](#video-editors)
- [After Video Processing is Done](#after-video-processing-is-done)
  - [Callback Data](#callback-data)
- [Video Guidelines](#video-guidelines)
- [Reference Guide](#reference-guide)

## Installation

### Step 1: Get API Access

Email **[support@pb.vision](mailto:support@pb.vision)** to request API access for your
account. Let us know which data you need access to (e.g. insights, stats) which
is documented below in the [Callback Data](#callback-data) section. We'll send
you an API Key after discussing your needs more in depth and laying out our billing options.

### Step 2: SDK Setup

1. Install [node](https://nodejs.org/en/download)
2. Install the SDK: `npm i @pbvision/partner-sdk`
3. In your package.json, make sure you're configured to use ESM (modules): `"type": "module"`
4. Initialize the SDK:

```javascript
import { PBVision } from '@pbvision/partner-sdk';
const pbv = new PBVision(YOUR_API_KEY);
```

5. Use its methods as described to [send us video URLs](#send-videos) to
   to process, or [tell us your webhook's URL](#webhook-setup).

## Using the API

### Webhook Setup

Each time our AI finishes processing a video, it will notify your servers via
an HTTP POST request to a URL ("webhook") of your choice. You can use our SDK
to tell our servers where you want us to notify your servers like this:

```javascript
import { PBVision } from '@pbvision/partner-sdk';

const pbv = new PBVision(YOUR_API_KEY);
await pbv.setWebhook(YOUR_WEBHOOK_URL);
```

Alternatively, you can just use `curl`:

```bash
curl -X POST \
     -H 'x-api-key: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{"url": "https://YOUR_WEBHOOK_URL"}' \
     https://api-2o2klzx4pa-uc.a.run.app/partner/webhook/set
```

### Send Videos

#### Option 1: PBV downloads your video from a URL

First, upload a video to a _publicly_ accessible URL on your server. For best
results, videos should follow our [guidelines](#video-guidelines).

Next, tell us to download and work on the video. You can do this using our SDK:

```javascript
import { PBVision } from '@pbvision/partner-sdk';

const pbv = new PBVision(YOUR_API_KEY, { useProdServer: true });
// you can omit this metadata, or provide some or all of this object—whatever you'd like!
const optionalMetadata = {
  userEmails: [], // these users will have the video in their PB Vision library
  name: 'Dink Championship 2025',
  gameStartEpoch: 1711393200, // when the game was played
};
await pbv.sendVideoUrlToDownload(YOUR_VIDEO_URL, optionalMetadata);
```

Alternatively, you can just use `curl`:

```bash
curl -X POST \
     -H 'x-api-key: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{"url": "https://YOUR_VIDEO_URL", "userEmails": ["test@example.com"]}' \
     https://api-2o2klzx4pa-uc.a.run.app/partner/add_video_by_url
```

#### Option 2: Upload your video

You can directly upload your video from a file using the SDK too:

```javascript
import { PBVision } from '@pbvision/partner-sdk';

const pbv = new PBVision(YOUR_API_KEY, { useProdServer: true });
// you can omit this metadata, or provide some or all of this object—whatever you'd like!
const optionalMetadata = {
  userEmails: [], // these users will have the video in their PB Vision library
  name: 'Dink Championship 2025',
  gameStartEpoch: 1711393200, // when the game was played
};
await pbv.uploadVideo(YOUR_VIDEO_FILENAME, optionalMetadata);
```

### Video Editors

Editors can tag themselves and friends in the video. They also have access to
the video even if the video is private (to make videos uploaded by your partner
account private by default, please let us know via email).

You can get the current list of editors on a video by using the `getVideoEditors()`
method. Similarly, the `setVideoEditors()` method can be used to change the
email addresses which have editor access on your video.

## After Video Processing is Done

When our AI is done processing your video, we will email the players in the
game (_if_ their email addresses were provided via `userEmails`). These users
will be "editors" on the video and be able to tag themselves and their friends.

If you [provided a webhook](#webhook-setup), then we'll send
an HTTP POST request to your server. Your server should acknowledge this
callback with a standard 200 (OK) response. If it does not, we will attempt to
retry sending this request later (up to some maximum number of attempts).

The HTTP POST body will contain JSON which looks like this (depending on which
data is enabled for your API key, only some of these fields may be present):

```json
{
    "from_url": "https://example.com/my-video.mp4",
    "webpage": "https://pb.vision/video/83gyqyc10y8f",
    "cv": CV_DATA,
    "insights": INSIGHTS_DATA,
    "stats": STATS_DATA,
    "vid": STRING,
    "aiEngineVersion": INT,
    "error": {
        "reason": "some explanation here..."
    }
}
```

### Callback Data

- `from_url` is the video url you sent us in [step 3](#send-videos)
- `webpage` is a link to our web app where the stats can be explored
- `error` is only present if your video could not be processed
- `cv` contains low-level frame-by-frame data
- `insights` describes the pickleball game in a detailed, shot-by-shot format
  - Explore the _insights_ schema at <https://pbv-public.github.io/insights>
  - Schema changes and diffs are in our [`pbv-public/insights` repo](https://github.com/pbv-public/insights/blob/dev/CHANGELOG.md)
- `stats` various stats about the game for advanced players
  - Explore the _stats_ schema at <https://pbv-public.github.io/stats?s=~stats~game>
  - Schema changes and diffs are in our [`pbv-public/stats` repo](https://github.com/pbv-public/stats/blob/dev/CHANGELOG.md)
- only included if `insights` is included:
  - `vid` - the unique ID of the video in our system
  - `aiEngineVersion` - the version number of our AI used to process the video
  - Using these two values, you can retrieve the player thumbnail images extracted from the video like: `https://storage.googleapis.com/pbv-pro/${vid}/${aiEngineVersion}/player${playerIndex}-${imageIndex}.jpg` where `playerIndex` is in the range [0, 3] (for doubles games) and `imageIndex` is in the range [0, 7].

## Video Guidelines

Requirements:

- Comply with [PB Vision's framing guidelines](https://help.pb.vision/en/help/articles/1108176-video-recording-and-framing-tips)
- Video Encoding: H.264 codec
- Frame Rate: 30 or 60 FPS
- Max Duration: 30 minutes

For best results, we also recommend:

- File Extension: .mp4
- Audio Encoding: MPEG-4 AAC
- Resolution: 1080p
- Frame Rate: 30 FPS
- Max Bitrate: 4 Mbps
- Max File Size: 2GB

## Reference Guide

- [JSDocs](https://pbv-public.github.io/partner-sdk-nodejs/)