About Pixellot

RestAPI documentation

Explore Partner API through our official documentation. This resource provides essential information for integrating our services seamlessly into your applications. Find detailed API endpoints, request methods, authentication guides, and error handling instructions.

For more information, visit our REST API documentation at https://app.swaggerhub.com/apis/Pixellot/partner_api/

Available environments:

[Base URL] = api.pixellot.tv/v1 (PROD) - production workloads
[Base URL] = api.stage.pixellot.tv/v1 (STAGE) - tests and integration

Integration steps

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

Subscribing to EventBreakdown

The Login endpoint should be called to get the API token. A request createSubscription should be called with the messageType field set to EventBreakdown.

Subscription request example:

1. curl --request POST 'https://api.pixellot.tv/v1/monitoring/subscriptions' \
   
2. --header 'Authorization: TOKEN' \
   
3. --header 'Content-Type: application/json' \
   
4. --data-raw '{ "messageType": "EventBreakdown", "tenant": "TENANT", "url": "https://example.compaby.domain.com/event-breakdown", "emails": "company@company.com", "secret": "somesecretvalue" }'
   

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 EventBreakdownHookMessageBody

Example client app source code

The app is created with NodeJS. It uses the ffmpef-fluent to build ffmpeg command programmatically

and moment to do the date and time operations.

The app generates 3 clips for a soccer advanced event breakdown: all shots, home team shots, and away team shots. generateClips function needs 2 arguments - the event and the breakdown. The event is sent in the EventBreakdownHookMessageBody in the event property.

package.json

1. {
     "name": "advanced-event-breakdown",
     "main": "index.js",
     "dependencies": {
       "fluent-ffmpeg": "^2.1.2",
       "moment": "^2.29.4"
     }
   }

index.js

1. const fs = require('fs');
   const path = require('path');
   const moment = require('moment');
   const FfmpegCommand = require('fluent-ffmpeg');
   
   const TMP_DIR_PATH = path.resolve(__dirname, 'tmp');
   
   /**
    * Function takes the event breakdown and returns only Shot tags
    */
   const getAllShotTags = (eventBreakdown) => eventBreakdown.filter((tag) => tag.tagResource.name === 'Shot');
   
   /**
    * Function takes the event breakdown and returns only Shot tags of a specific team
    */
   const getTeamShotTags = (eventBreakdown, teamName) => eventBreakdown.filter((tag) => {
       const isShotTag = tag.tagResource.name === 'Shot';
   
       if (isShotTag) {
           const teamTagAttribure = tag.tagAttributes.find((tagAttribute) => tagAttribute.name === 'Team');
   
           if (teamTagAttribure && teamTagAttribure.value === teamName) {
               return true;
           }
       }
   
       return false;
   });
   
   /**
    * Function creates one clip from the provided tags
    * Step 1:  Clean the tmp directory
    * Step 2:  Covert the tag startOffset and endOffset to the format that is respected by the ffmpeg
    *          { clipStart: number, clipDuration: number },
    *          where `clipStart` is start of the clip on the source video in seconds and clipDuration is the duration of the clip
    * Step 3:  Initialize `chunksFileContent` variable to an empty string. This variable will hold the content that will be written to the chunks.txt
    *          chunks.txt will be provided to ffmpeg to concat generated clips
    * Step 4:  Create clips and save them to the tmp folder
    * Step 5:  Write the `chunksFileContent` to the chunks.txt file
    * Step 5:  Concat the files and save the clip to the `outputFilePath`
    */
   const createClipFromTags = async (videoUrl, tags, outputFilePath) => {
       // Step 1
       fs.readdirSync(TMP_DIR_PATH).forEach((f) => fs.rmSync(`${TMP_DIR_PATH}/${f}`));
   
       // Step 2
       const ffmpegTimestamps = tags.map(({ startOffset, endOffset }) => {
           const startOffsetSeconds = moment.duration(startOffset).asSeconds();
           const endOffsetDurationSeconds = moment.duration(endOffset).asSeconds();
   
           return {
               clipStart: startOffsetSeconds,
               clipDuration: endOffsetDurationSeconds - startOffsetSeconds,
           };
       });
   
       // Step 3
       let chunksFileContent = '';
   
       // Step 4
       await Promise.all(ffmpegTimestamps.map(({ clipDuration, clipStart }) => {
           const fileName = `${clipStart}-${clipDuration}.mp4`;
   
           chunksFileContent += `file ${fileName}\n`;
   
           return new Promise((resolve) => {
               new FfmpegCommand()
                   .addInput(videoUrl)
                   .addOption('-ss', clipStart)
                   .addOption('-t', clipDuration)
                   .addOutput(path.resolve(TMP_DIR_PATH, `${clipStart}-${clipDuration}.mp4`))
                   .on('end', resolve)
                   .run();
           });
       }));
   
       // Step 5
       fs.writeFileSync(path.resolve(TMP_DIR_PATH, 'chunks.txt'), chunksFileContent);
   
       // Step 6
       await new Promise((resolve) => {
           new FfmpegCommand()
               .input(path.resolve(TMP_DIR_PATH, 'chunks.txt'))
               .inputOptions(['-f concat', '-safe 0'])
               .outputOptions('-c copy')
               .on('end', resolve)
               .save(outputFilePath);
       });
   };
   
   const generateClips = async (event, eventBreakdown) => {
       const {
           labels: {
               teams: {
                   homeTeamName,
                   awayTeamName,
               },
           },
           locallyRecordedHdMp4Url,
       } = event;
   
       const shotsTags = getAllShotTags(eventBreakdown);
       const homeTeamShots = getTeamShotTags(eventBreakdown, homeTeamName);
       const awayTeamShots = getTeamShotTags(eventBreakdown, awayTeamName);
   
       await createClipFromTags(locallyRecordedHdMp4Url, shotsTags, path.resolve(__dirname, 'clips', 'allShots.mp4'));
       await createClipFromTags(locallyRecordedHdMp4Url, homeTeamShots, path.resolve(__dirname, 'clips', 'homeTeamShots.mp4'));
       await createClipFromTags(locallyRecordedHdMp4Url, awayTeamShots, path.resolve(__dirname, 'clips', 'awayTeamShots.mp4'));
   };
   
   generateClips(
       {
           labels: {
               teams: {
                   homeTeamName: 'Home',
                   awayTeamName: 'Away',
               },
           },
           locallyRecordedHdMp4Url: path.resolve(__dirname, 'video', 'video.mp4'),
       },
       [
           {
               startOffset: '00:02:00',
               endOffset: '00:02:05',
               tagResource: {
                   name: 'Shot',
               },
               tagAttributes: [
                   {
                       name: 'Team',
                       value: 'Home',
                   },
               ],
           },
           {
               startOffset: '00:03:00',
               endOffset: '00:03:05',
               tagResource: {
                   name: 'Shot',
               },
               tagAttributes: [
                   {
                       name: 'Team',
                       value: 'Away',
                   },
               ],
           },
           {
               startOffset: '00:04:00',
               endOffset: '00:04:05',
               tagResource: {
                   name: 'Shot',
               },
               tagAttributes: [
                   {
                       name: 'Team',
                       value: 'Away',
                   },
               ],
           },
       ],
   );