This doc includes materials that help other companies integrate with the Pixellot ecosystem. From Pixellot’s perspective, a company that joins the marketplace becomes VAS - Value Added Service.

How to use the doc?

1. VAS needs to decide what type of integration suits the company service, by looking at supported VAS types.
2. After selecting the type, VAS needs to provide data described in the First steps.
   
3. Now the integration should be implemented from the VAS side. The set of use-cases that needs to be covered is described in Flows section. REST API Documentation and Pixellot events subscription (see section 5) explains the technical details of the Pixellot API and integrate methodology.
   

This page references API calls and models described in REST API documentation and Pixellot events subscription.

VAS Types

As of now, Pixellot supports three VAS types:

A. Enhancement of real-time RTMP feed - Video Enhancer

B. Adding a pre-rendered graphics overlay - Overlay Provider

C. Upload camera raw data to cloud - Raw Data Consumer

More to come soon…

Example request:

1. curl --request PATCH 'https://api.pixellot.tv/v1/events/EVENT_ID/vas/VAS_NAME' \
   --header 'Authorization: TOKEN' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "forwardUrl": "rtmp://test.domain.com/forwardUrl",
       "controlUrl": "https://test.domain.com/controlUrl",
   }'

Response:

1. {
       "eventName": "VAS Test",
         ...
       "vas": {
           "overlayProvider": {
               "name": "overlay-vas",
               "forwardUrl": "rtmp://test.domain.com/forwardUrl",
               "controlUrl": "https://test.domain.com/controlUrl"
           }
       }
   }

Flow:

This type of VAS allow upload of .mkv raw video to a third-party S3 bucket.

Enabling the upload raw video on the event level is achieved by using VAS. This type of VAS can be added alongside the other type of VASes.

After adding the vas to the event, the VAS will call API with the URL to be used later to get upload details (uploadDetailsCallback field).

Event data will look as follows:

1.  "vas": {
           "rawDataConsumer": {
               "name":"provider-name", // any other provider
               "uploadDetailsCallback": "...us-east-1.amazonaws.com/alpha/getUploadDetails" // the endpoint to call to return upload details
               "uploadCompleteCallback": "...us-east-1.amazonaws.com/alpha/completeUpload"  // to notify on raw uploaded
           }
       }

Flow:

This section describes the initial steps of the integration.

VAS Data

There are some pieces of information that need to be exchanged between Pixellot and VAS to initiate the integration.

Data to provide by the VAS owner:

1. Description - a brief description of the service, what it provides. This text will be shown in the marketplace where tenants will decide which VAS to use.
2. Icon URL - a link to the company icon.
3. Website URL - a link to the company web-site.
4. Join and leave callbacks - the POST HTTP endpoint URLs that will be called on tenant join/leave. More on this - see Tenant adds VAS in the marketplace and Tenant removes VAS in the marketplace sections of this document.
5. [Optional] join and leave callbacks secrets. When sending the data, an HMAC hex digest is used to compute a hash from the sent payload (without whitespaces). The hash will be placed in the X-Pixellot-Signature header.
   

In response to this data, Pixellot will provide:

• username and password that should be used in the REST API login requests to get the token

• VAS name - a unique name for the VAS. Will be used in the REST API requests related to VAS operations.

API restrictions

The VAS details should be added at least 15 minutes before the event start. All requests 15 minutes before the event start and later will be discarded.

However, it is possible to modify events with VAS type Overlay Provider to start in the nearest future, ignoring the 15-minute restriction.

Pixellot provides a convenient Pixellot to VAS communication approach. It is a subscription mechanism, where VAS gives a URL to Pixellot that needs to be called when an action happens. How does it work in a nutshell - VAS subscribes to a specific topic, like eventUpdate or teamUpdate, by providing an HTTP webhook URL that will be called once an action happens?

The subscriptions are for notification purposes only - the HTTP response is ignored, except for failures. If a subscription has many failures - an email about it will be sent to the email that was specified in the subscription creation body. 

1. Subscribing to event changes

This subscription should be created while handling the joinCallback (more on it Tenant adds VAS in the marketplace section). The subscription type is specified in the messageType field and should be VasEventTimestamp in this case.

Subscription request example:

After subscribing to the event changes, requests will be sent to the URL specified in the request body. Messages will be in the format of EventChangeHookMessageBody

The top-level property what of EventChangeHookMessageBody is a string that can be one of 4 possible values: created, updated, removed, and deleted.

1. created - when the VAS was added to the event. After this message, VAS may update the VAS details by calling the PATCH /events/:id/vas/:vasName endpoint
2. updated - when the event had an update: name, date, team - any field. The whole updated entity is sent - not only the updates
   
3. removed - when the VAS was removed from the event
   
4. deleted - when the event was deleted

For the VAS of type videoEnhancer, the inputUrl, to which the stream should be forwarded after enhancement can be found by this path: 

.event.vas.videoEnhancer.inputUrl.

2. Subscribing to team changes

This subscription may also be created while handling the joinCallback. The messageType for this subscription should be VasTeamChange.

After subscribing to the event changes, requests will be sent to the URL specified in the request body. Messages will be in the format of TeamChangeHookMessageBody.

​

1. Tenant adds VAS in the marketplace

This is the first interaction between the tenant and VAS. When VAS is added to the tenant, Pixellot sends a request to the VAS join callback, with the payload CallbackRequestData (action: join). VAS should create a subscription, by calling the createSubscription API.

The diagram shows that VAS should call the createSubscription API when the join callback endpoint is hit. If the subscription was successfully created, the 2XX HTTP status code is expected to be returned from the join callback call. If an error occurs during subscription creation, an error should be returned from the join callback call.

It is important to have a maximum possible uptime of a join callback endpoint - otherwise, your VAS will not be obtainable through Marketplace.

2.  Tenant removes VAS in the marketplace

The tenant decides that he wants to remove the VAS. When this happens, Pixellot calls the leave callback with the payload CallbackRequestData (action: leave). The VAS should not call any endpoint in response to this call. If the request will be processed successfully, Pixellot expects to get a 2XX HTTP response.

The subscriptions will be deleted automatically

3. Tenant adds VAS to the event

After the tenant adds VAS, it can add VAS to the events. When the tenant adds VAS to the event, the VAS receives a notification about it (more on this in Subscribing to event changes section). The VAS backend receives the EventChangeHookMessageBody with the top-level property what set to created. In response to the create messages, the VAS may call the addVasDetails API to add the details to the event. As mentioned in the Pixellot events subscription (see section 5), the response of the notification request is ignored, so setting the event details should be a separate action.

            

4. The VASed event is updated

When the event with VAS added to it gets updated, the VAS receives a notification about it with the top-level property what set to updated. The whole event model is sent in the notification, not only the updates. The needed updates should happen on the VAS side. If the event updates affect the previously set VAS details on event (the addVasDetails API call), the VAS data can be updated on the event through the same request.

5. Tenant removes VAS from the event

When the tenant removes VAS from the event, the VAS receives a notification about it with the top-level property what set to removed. No actions are expected from VAS to Pixellot - both parties just clean up the resources created to support this VASed event.

6. Tenant deletes the event

When the event is deleted, the VAS receives a notification about it with the top-level property what being set to deleted. The same behavior takes place as if the tenant removed the VAS from the event.