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
});