Eve library

Node.js Integration Guide

Guide

Revision 1

On this page

This guide covers integrating the Aja Motion Pipeline into Node.js applications for server-side video processing.

Installation#

bash
pnpm add @aja/motion-pipeline-sdk
# or
npm install @aja/motion-pipeline-sdk

Basic Setup#

Environment Configuration#

Create a .env file with your API credentials:

env
AJA_API_URL=https://api.aja.oshun.io
AJA_API_KEY=your-api-key-here

Client Factory#

Create a reusable client factory:

typescript
// src/lib/aja-client.ts
import {
  createClient,
  type MotionPipelineClient,
} from '@aja/motion-pipeline-sdk';

let client: MotionPipelineClient | null = null;

export function getAjaClient(): MotionPipelineClient {
  if (!client) {
    client = createClient({
      baseUrl: process.env.AJA_API_URL!,
      auth: {
        type: 'api-key',
        apiKey: process.env.AJA_API_KEY!,
      },
      retry: {
        maxAttempts: 3,
        initialDelayMs: 1000,
        maxDelayMs: 10000,
        multiplier: 2,
      },
      timeoutMs: 30000,
    });
  }
  return client;
}

Express.js Integration#

Video Upload Endpoint#

typescript
// src/routes/motion.ts
import express from 'express';
import multer from 'multer';
import { getAjaClient } from '../lib/aja-client';
import { configId } from '@aja/motion-pipeline-sdk';

const router = express.Router();
const upload = multer({ dest: 'uploads/' });

// Submit video for motion extraction
router.post('/extract', upload.single('video'), async (req, res) => {
  try {
    const client = getAjaClient();
    const { preset = 'standard', domain = 'general' } = req.body;

    if (!req.file) {
      return res.status(400).json({ error: 'No video file provided' });
    }

    // Upload to storage and get URL
    const videoUrl = await uploadToStorage(req.file.path);

    const result = await client.submitJob({
      input: {
        type: 'url',
        url: videoUrl,
        filename: req.file.originalname,
      },
      pipelineConfig: {
        name: `user-${req.user?.id}-${Date.now()}`,
        domain: domain as 'general' | 'dance' | 'yoga' | 'fitness',
        qualityPreset: preset as 'draft' | 'standard' | 'high' | 'ultra',
      },
      options: {
        webhook: {
          url: `${process.env.APP_URL}/webhooks/aja`,
          events: ['completed', 'failed'],
        },
        tags: [`user:${req.user?.id}`],
      },
    });

    if (!result.success) {
      return res.status(500).json({ error: result.error.message });
    }

    res.json({
      jobId: result.data.jobId,
      message: 'Video submitted for processing',
    });
  } catch (error) {
    console.error('Motion extraction error:', error);
    res.status(500).json({ error: 'Failed to process video' });
  }
});

// Get job status
router.get('/jobs/:jobId', async (req, res) => {
  try {
    const client = getAjaClient();
    const { jobId } = req.params;

    const result = await client.getJob(jobId as any);

    if (!result.success) {
      return res.status(404).json({ error: 'Job not found' });
    }

    res.json(result.data);
  } catch (error) {
    res.status(500).json({ error: 'Failed to get job status' });
  }
});

// Download processed motion
router.get('/jobs/:jobId/download', async (req, res) => {
  try {
    const client = getAjaClient();
    const { jobId } = req.params;
    const { format = 'fbx' } = req.query;

    const result = await client.generateDownloadUrl(jobId as any, {
      format: format as string,
      expiresIn: 3600,
    });

    if (!result.success) {
      return res.status(404).json({ error: 'Download not available' });
    }

    res.redirect(result.data.url);
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate download URL' });
  }
});

export default router;

Webhook Handler#

typescript
// src/routes/webhooks.ts
import express from 'express';
import { jobId } from '@aja/motion-pipeline-sdk';

const router = express.Router();

interface AjaWebhookPayload {
  event: 'completed' | 'failed';
  jobId: string;
  timestamp: string;
  data: {
    status: string;
    outputs?: Array<{
      format: string;
      name: string;
      sizeBytes: number;
    }>;
    error?: {
      code: string;
      message: string;
    };
  };
}

router.post('/aja', async (req, res) => {
  const payload = req.body as AjaWebhookPayload;

  console.log(`Received webhook: ${payload.event} for job ${payload.jobId}`);

  try {
    switch (payload.event) {
      case 'completed':
        await handleJobCompleted(payload);
        break;
      case 'failed':
        await handleJobFailed(payload);
        break;
    }

    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).send('Error processing webhook');
  }
});

async function handleJobCompleted(payload: AjaWebhookPayload) {
  const { jobId, data } = payload;

  // Update database
  await db.jobs.update({
    where: { externalId: jobId },
    data: {
      status: 'completed',
      outputs: data.outputs,
      completedAt: new Date(),
    },
  });

  // Notify user
  await notifications.send({
    userId: await getUserForJob(jobId),
    type: 'motion_ready',
    message: 'Your motion capture is ready!',
    data: { jobId },
  });
}

async function handleJobFailed(payload: AjaWebhookPayload) {
  const { jobId, data } = payload;

  await db.jobs.update({
    where: { externalId: jobId },
    data: {
      status: 'failed',
      error: data.error?.message,
      completedAt: new Date(),
    },
  });

  await notifications.send({
    userId: await getUserForJob(jobId),
    type: 'motion_failed',
    message: 'Motion extraction failed',
    data: { jobId, error: data.error?.message },
  });
}

export default router;

Fastify Integration#

typescript
// src/plugins/aja.ts
import { FastifyPluginAsync } from 'fastify';
import fp from 'fastify-plugin';
import {
  createClient,
  type MotionPipelineClient,
} from '@aja/motion-pipeline-sdk';

declare module 'fastify' {
  interface FastifyInstance {
    aja: MotionPipelineClient;
  }
}

const ajaPlugin: FastifyPluginAsync = async (fastify) => {
  const client = createClient({
    baseUrl: fastify.config.AJA_API_URL,
    auth: {
      type: 'api-key',
      apiKey: fastify.config.AJA_API_KEY,
    },
  });

  fastify.decorate('aja', client);

  // Health check
  fastify.get('/health/aja', async () => {
    const result = await client.health();
    if (!result.success) {
      throw new Error('Aja service unhealthy');
    }
    return result.data;
  });
};

export default fp(ajaPlugin, {
  name: 'aja',
  dependencies: ['config'],
});
typescript
// src/routes/motion.ts
import { FastifyPluginAsync } from 'fastify';

const motionRoutes: FastifyPluginAsync = async (fastify) => {
  fastify.post(
    '/motion/extract',
    {
      schema: {
        body: {
          type: 'object',
          required: ['videoUrl'],
          properties: {
            videoUrl: { type: 'string', format: 'uri' },
            preset: {
              type: 'string',
              enum: ['draft', 'standard', 'high', 'ultra'],
            },
            domain: {
              type: 'string',
              enum: ['general', 'dance', 'yoga', 'fitness'],
            },
          },
        },
      },
    },
    async (request, reply) => {
      const {
        videoUrl,
        preset = 'standard',
        domain = 'general',
      } = request.body as any;

      const result = await fastify.aja.submitJob({
        input: {
          type: 'url',
          url: videoUrl,
          filename: new URL(videoUrl).pathname.split('/').pop() ?? 'video.mp4',
        },
        pipelineConfig: {
          name: `api-${Date.now()}`,
          domain,
          qualityPreset: preset,
        },
      });

      if (!result.success) {
        return reply.status(500).send({ error: result.error.message });
      }

      return { jobId: result.data.jobId };
    }
  );
};

export default motionRoutes;

Background Job Processing#

Using BullMQ#

typescript
// src/queues/motion-queue.ts
import { Queue, Worker, Job } from 'bullmq';
import { getAjaClient } from '../lib/aja-client';
import { jobId } from '@aja/motion-pipeline-sdk';

interface MotionJobData {
  videoUrl: string;
  userId: string;
  preset: 'draft' | 'standard' | 'high' | 'ultra';
  domain: 'general' | 'dance' | 'yoga' | 'fitness';
  outputFormats: string[];
}

// Create queue
export const motionQueue = new Queue<MotionJobData>('motion', {
  connection: {
    host: process.env.REDIS_HOST,
    port: parseInt(process.env.REDIS_PORT ?? '6379'),
  },
});

// Add job to queue
export async function queueMotionExtraction(data: MotionJobData) {
  return motionQueue.add('extract', data, {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 5000,
    },
  });
}

// Process queue
export const motionWorker = new Worker<MotionJobData>(
  'motion',
  async (job: Job<MotionJobData>) => {
    const client = getAjaClient();
    const { videoUrl, userId, preset, domain, outputFormats } = job.data;

    // Submit to Aja
    const submitResult = await client.submitJob({
      input: {
        type: 'url',
        url: videoUrl,
        filename: `user-${userId}-video.mp4`,
      },
      pipelineConfig: {
        name: `queue-${job.id}`,
        domain,
        qualityPreset: preset,
      },
      options: {
        tags: [`user:${userId}`, `queue:${job.id}`],
      },
    });

    if (!submitResult.success) {
      throw new Error(submitResult.error.message);
    }

    const ajaJobId = submitResult.data.jobId;

    // Poll for completion
    let attempts = 0;
    const maxAttempts = 360; // 30 minutes at 5 second intervals

    while (attempts < maxAttempts) {
      const statusResult = await client.getJob(ajaJobId as any);

      if (!statusResult.success) {
        throw new Error('Failed to get job status');
      }

      const status = statusResult.data.status;

      // Update progress
      job.updateProgress(statusResult.data.progress ?? 0);

      if (status === 'completed') {
        // Get download URLs
        const outputs = await Promise.all(
          outputFormats.map(async (format) => {
            const dlResult = await client.generateDownloadUrl(ajaJobId as any, {
              format,
            });
            return dlResult.success ? { format, url: dlResult.data.url } : null;
          })
        );

        return {
          ajaJobId,
          outputs: outputs.filter(Boolean),
        };
      }

      if (status === 'failed' || status === 'cancelled') {
        throw new Error(
          `Job ${status}: ${statusResult.data.error ?? 'Unknown error'}`
        );
      }

      // Wait before next poll
      await new Promise((resolve) => setTimeout(resolve, 5000));
      attempts++;
    }

    throw new Error('Job timed out');
  },
  {
    connection: {
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT ?? '6379'),
    },
    concurrency: 5,
  }
);

// Event handlers
motionWorker.on('completed', (job, result) => {
  console.log(`Job ${job.id} completed:`, result);
});

motionWorker.on('failed', (job, error) => {
  console.error(`Job ${job?.id} failed:`, error.message);
});

Streaming with SSE#

Server Implementation#

typescript
// src/routes/stream.ts
import express from 'express';
import { getAjaClient } from '../lib/aja-client';
import { jobId } from '@aja/motion-pipeline-sdk';

const router = express.Router();

router.get('/jobs/:jobId/stream', async (req, res) => {
  const { jobId: id } = req.params;

  // Set up SSE headers
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const client = getAjaClient();

  // Stream events from Aja
  const unsubscribe = client.streamJobProgress(id as any, {
    onProgress: (event) => {
      res.write(`event: progress\n`);
      res.write(`data: ${JSON.stringify(event.data)}\n\n`);
    },
    onStageChange: (event) => {
      res.write(`event: stage\n`);
      res.write(`data: ${JSON.stringify(event.data)}\n\n`);
    },
    onComplete: (event) => {
      res.write(`event: complete\n`);
      res.write(`data: ${JSON.stringify(event.data)}\n\n`);
      res.end();
    },
    onError: (event) => {
      res.write(`event: error\n`);
      res.write(`data: ${JSON.stringify(event.data)}\n\n`);
      res.end();
    },
  });

  // Handle client disconnect
  req.on('close', () => {
    unsubscribe();
  });
});

export default router;

Error Handling#

Custom Error Classes#

typescript
// src/errors/aja-errors.ts
export class AjaError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'AjaError';
  }
}

export class AjaQuotaExceededError extends AjaError {
  constructor(message: string) {
    super(message, 'QUOTA_EXCEEDED');
    this.name = 'AjaQuotaExceededError';
  }
}

export class AjaValidationError extends AjaError {
  constructor(message: string, details?: Record<string, unknown>) {
    super(message, 'VALIDATION_ERROR', details);
    this.name = 'AjaValidationError';
  }
}

Error Handler Middleware#

typescript
// src/middleware/error-handler.ts
import { Request, Response, NextFunction } from 'express';
import { AjaError } from '../errors/aja-errors';

export function ajaErrorHandler(
  error: Error,
  req: Request,
  res: Response,
  next: NextFunction
) {
  if (error instanceof AjaError) {
    return res.status(getStatusCode(error.code)).json({
      error: error.message,
      code: error.code,
      details: error.details,
    });
  }
  next(error);
}

function getStatusCode(code: string): number {
  switch (code) {
    case 'QUOTA_EXCEEDED':
      return 429;
    case 'VALIDATION_ERROR':
      return 400;
    case 'NOT_FOUND':
      return 404;
    case 'UNAUTHORIZED':
      return 401;
    default:
      return 500;
  }
}

Testing#

Unit Tests with Vitest#

typescript
// src/__tests__/motion-service.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { MotionService } from '../services/motion-service';

// Mock the SDK
vi.mock('@aja/motion-pipeline-sdk', () => ({
  createClient: vi.fn(() => ({
    submitJob: vi.fn(),
    getJob: vi.fn(),
    health: vi.fn(),
  })),
  jobId: vi.fn((id) => id),
  configId: vi.fn((id) => id),
}));

describe('MotionService', () => {
  let service: MotionService;
  let mockClient: any;

  beforeEach(() => {
    const { createClient } = require('@aja/motion-pipeline-sdk');
    mockClient = createClient();
    service = new MotionService(mockClient);
  });

  it('should submit a job successfully', async () => {
    mockClient.submitJob.mockResolvedValue({
      success: true,
      data: { jobId: 'job-123' },
    });

    const result = await service.extractMotion({
      videoUrl: 'https://example.com/video.mp4',
      preset: 'standard',
    });

    expect(result.jobId).toBe('job-123');
    expect(mockClient.submitJob).toHaveBeenCalledWith(
      expect.objectContaining({
        input: expect.objectContaining({
          type: 'url',
          url: 'https://example.com/video.mp4',
        }),
      })
    );
  });

  it('should handle submission errors', async () => {
    mockClient.submitJob.mockResolvedValue({
      success: false,
      error: { code: 'INVALID_INPUT', message: 'Invalid video format' },
    });

    await expect(
      service.extractMotion({
        videoUrl: 'https://example.com/invalid.txt',
        preset: 'standard',
      })
    ).rejects.toThrow('Invalid video format');
  });
});

Integration Tests#

typescript
// src/__tests__/integration/motion.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import request from 'supertest';
import { app } from '../../app';

describe('Motion API Integration', () => {
  // Skip in CI unless AJA_API_KEY is set
  const skipIfNoApiKey = process.env.AJA_API_KEY ? it : it.skip;

  skipIfNoApiKey(
    'should submit and complete a motion extraction job',
    async () => {
      // Submit job
      const submitResponse = await request(app)
        .post('/api/motion/extract')
        .send({
          videoUrl: 'https://test-videos.aja.oshun.io/sample-dance.mp4',
          preset: 'draft',
          domain: 'dance',
        });

      expect(submitResponse.status).toBe(200);
      expect(submitResponse.body.jobId).toBeDefined();

      const { jobId } = submitResponse.body;

      // Poll for completion (with timeout)
      let status = 'pending';
      let attempts = 0;
      const maxAttempts = 60; // 5 minutes

      while (
        status !== 'completed' &&
        status !== 'failed' &&
        attempts < maxAttempts
      ) {
        await new Promise((r) => setTimeout(r, 5000));

        const statusResponse = await request(app).get(
          `/api/motion/jobs/${jobId}`
        );
        status = statusResponse.body.status;
        attempts++;
      }

      expect(status).toBe('completed');
    },
    300000
  ); // 5 minute timeout
});