The @aja/motion-pipeline-sdk package provides a type-safe TypeScript client
for interacting with the Aja Motion Pipeline API.
Installation#
pnpm add @aja/motion-pipeline-sdk
# or
npm install @aja/motion-pipeline-sdk
# or
yarn add @aja/motion-pipeline-sdk
Quick Start#
import { createClient } from '@aja/motion-pipeline-sdk';
// Create a client instance
const client = createClient({
baseUrl: 'https://api.aja.oshun.io',
auth: {
type: 'api-key',
apiKey: 'your-api-key',
},
});
// Submit a video for processing
const result = await client.submitJob({
input: {
type: 'url',
url: 'https://example.com/dance-video.mp4',
filename: 'dance-video.mp4',
},
pipelineConfig: {
name: 'my-dance-config',
domain: 'dance',
qualityPreset: 'high',
},
});
if (result.success) {
console.log('Job submitted:', result.data.jobId);
}
Client Configuration#
createClient(config: ClientConfig): MotionPipelineClient#
Creates a new SDK client instance.
Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
baseUrl |
string |
Yes | Base URL of the Motion Pipeline API |
auth |
AuthConfig |
Yes | Authentication configuration |
retry |
RetryConfig |
No | Retry behavior configuration |
timeoutMs |
number |
No | Request timeout in milliseconds (default: 30000) |
Auth Configuration#
// API Key Authentication
const client = createClient({
baseUrl: 'https://api.aja.oshun.io',
auth: {
type: 'api-key',
apiKey: 'your-api-key',
},
});
// Bearer Token Authentication
const client = createClient({
baseUrl: 'https://api.aja.oshun.io',
auth: {
type: 'bearer',
token: 'your-jwt-token',
},
});
// No Authentication (for local development)
const client = createClient({
baseUrl: 'http://localhost:3000',
auth: { type: 'none' },
});
Retry Configuration#
const client = createClient({
baseUrl: 'https://api.aja.oshun.io',
auth: { type: 'api-key', apiKey: 'your-key' },
retry: {
maxAttempts: 3, // Maximum retry attempts
initialDelayMs: 1000, // Initial delay between retries
maxDelayMs: 10000, // Maximum delay between retries
multiplier: 2, // Exponential backoff multiplier
},
});
Job Management#
submitJob(request: CreateJobRequest): Promise<Result<JobSubmitResponse>>#
Submits a new video for processing.
Input Types#
// URL Input
const result = await client.submitJob({
input: {
type: 'url',
url: 'https://example.com/video.mp4',
filename: 'video.mp4',
},
pipelineConfig: configId('config-123'),
});
// Storage Path Input
const result = await client.submitJob({
input: {
type: 'storage',
storagePath: '/videos/my-video.mp4',
filename: 'my-video.mp4',
},
pipelineConfig: {
name: 'inline-config',
domain: 'general',
qualityPreset: 'standard',
},
});
Job Options#
const result = await client.submitJob({
input: { type: 'url', url: videoUrl, filename: 'video.mp4' },
pipelineConfig: configId('config-123'),
options: {
priority: 'high', // 'critical' | 'high' | 'normal' | 'low' | 'background'
tags: ['production', 'dance'], // Organization tags
timeoutMs: 3600000, // Processing timeout (1 hour)
webhook: {
// Webhook notification
url: 'https://your-app.com/webhooks/aja',
events: ['completed', 'failed'],
},
},
});
getJob(id: JobId): Promise<Result<Job>>#
Gets details of a specific job.
import { jobId } from '@aja/motion-pipeline-sdk';
const result = await client.getJob(jobId('job-abc-123'));
if (result.success) {
const job = result.data;
console.log('Status:', job.status);
console.log('Progress:', job.progress);
console.log('Created:', job.createdAt);
}
listJobs(query?: JobListQuery): Promise<Result<JobListResponse>>#
Lists jobs with optional filtering.
// List all jobs
const result = await client.listJobs();
// Filter by status
const pending = await client.listJobs({ status: 'pending' });
// Filter by tags
const production = await client.listJobs({ tags: ['production'] });
// Paginated results
const page2 = await client.listJobs({
limit: 20,
offset: 20,
status: 'completed',
});
if (result.success) {
console.log(`Found ${result.data.total} jobs`);
for (const job of result.data.jobs) {
console.log(`${job.id}: ${job.status}`);
}
}
cancelJob(id: JobId): Promise<Result<void>>#
Cancels a running or queued job.
const result = await client.cancelJob(jobId('job-abc-123'));
if (result.success) {
console.log('Job cancelled successfully');
}
retryJob(id: JobId): Promise<Result<JobSubmitResponse>>#
Retries a failed job.
const result = await client.retryJob(jobId('job-abc-123'));
if (result.success) {
console.log('New job ID:', result.data.jobId);
}
Streaming Progress#
streamJobProgress(id: JobId, handlers: StreamHandlers): () => void#
Streams real-time progress updates for a job using Server-Sent Events.
import { jobId } from '@aja/motion-pipeline-sdk';
const unsubscribe = client.streamJobProgress(jobId('job-abc-123'), {
onProgress: (event) => {
console.log(`Stage: ${event.data.stage}`);
console.log(`Progress: ${(event.data.progress * 100).toFixed(1)}%`);
},
onStageChange: (event) => {
console.log(`Now processing: ${event.data.stage}`);
},
onComplete: (event) => {
console.log('Job completed!');
console.log('Outputs:', event.data.outputs);
},
onError: (event) => {
console.error('Job failed:', event.data.error);
},
});
// Stop streaming when done
unsubscribe();
Stream Event Types#
interface StreamEvent {
type: 'progress' | 'stage_change' | 'complete' | 'error' | 'heartbeat';
timestamp: string;
data: {
jobId: string;
stage?: string;
progress?: number;
message?: string;
outputs?: JobOutput[];
error?: string;
};
}
Output Management#
listOutputs(id: JobId): Promise<Result<OutputListResponse>>#
Lists all output files for a completed job.
const result = await client.listOutputs(jobId('job-abc-123'));
if (result.success) {
for (const output of result.data.outputs) {
console.log(`${output.name}: ${output.format} (${output.sizeBytes} bytes)`);
}
}
generateDownloadUrl(id: JobId, options: DownloadOptions): Promise<Result<DownloadUrlResponse>>#
Generates a signed download URL for job outputs.
const result = await client.generateDownloadUrl(jobId('job-abc-123'), {
format: 'fbx',
expiresIn: 3600, // URL expires in 1 hour
});
if (result.success) {
console.log('Download URL:', result.data.url);
console.log('Expires:', result.data.expiresAt);
}
Configuration Management#
createConfig(config: CreateConfigRequest): Promise<Result<ConfigCreateResponse>>#
Creates a new pipeline configuration.
const result = await client.createConfig({
name: 'dance-production',
description: 'High-quality dance motion capture',
domain: 'dance',
qualityPreset: 'high',
});
if (result.success) {
console.log('Config created:', result.data.id);
}
getConfig(id: ConfigId): Promise<Result<PipelineConfiguration>>#
Gets a specific configuration by ID.
import { configId } from '@aja/motion-pipeline-sdk';
const result = await client.getConfig(configId('config-123'));
if (result.success) {
console.log('Config:', result.data.name);
console.log('Domain:', result.data.domain);
console.log('Preset:', result.data.qualityPreset);
}
getConfigByName(name: string): Promise<Result<PipelineConfiguration>>#
Gets a configuration by its name.
const result = await client.getConfigByName('dance-production');
if (result.success) {
console.log('Found config:', result.data.id);
}
listConfigs(query?: ConfigListQuery): Promise<Result<ConfigListResponse>>#
Lists all configurations.
const result = await client.listConfigs();
if (result.success) {
for (const config of result.data.configs) {
console.log(`${config.name}: ${config.domain} (${config.qualityPreset})`);
}
}
updateConfig(id: ConfigId, updates: UpdateConfigRequest): Promise<Result<PipelineConfiguration>>#
Updates an existing configuration.
const result = await client.updateConfig(configId('config-123'), {
description: 'Updated description',
qualityPreset: 'ultra',
});
if (result.success) {
console.log('Config updated');
}
deleteConfig(id: ConfigId): Promise<Result<void>>#
Deletes a configuration.
const result = await client.deleteConfig(configId('config-123'));
if (result.success) {
console.log('Config deleted');
}
Health & Monitoring#
health(): Promise<Result<ServiceHealth>>#
Gets the health status of the service.
const result = await client.health();
if (result.success) {
console.log('Status:', result.data.status);
console.log('Uptime:', result.data.uptimeSeconds, 'seconds');
for (const [name, component] of Object.entries(
result.data.components ?? {}
)) {
console.log(`${name}: ${component.status}`);
}
}
queueStats(): Promise<Result<QueueStats>>#
Gets queue statistics.
const result = await client.queueStats();
if (result.success) {
const stats = result.data;
console.log('Waiting:', stats.waiting);
console.log('Active:', stats.active);
console.log('Completed:', stats.completed);
console.log('Failed:', stats.failed);
}
Type Definitions#
Branded Types#
The SDK uses branded types for IDs to ensure type safety:
import {
jobId,
configId,
type JobId,
type ConfigId,
} from '@aja/motion-pipeline-sdk';
// Create branded IDs from strings
const jid: JobId = jobId('job-abc-123');
const cid: ConfigId = configId('config-xyz-456');
// Type-safe function calls
client.getJob(jid); // ✓ Valid
client.getJob('string'); // ✗ Type error
Result Type#
All SDK methods return a Result type for explicit error handling:
type Result<T> =
| { success: true; data: T }
| { success: false; error: ApiError };
interface ApiError {
code: string;
message: string;
details?: Record<string, unknown>;
}
Job Status#
type JobStatus =
| 'pending' // Job created, not yet queued
| 'queued' // Job in queue, waiting for worker
| 'processing' // Job actively being processed
| 'completed' // Job finished successfully
| 'failed' // Job failed with error
| 'cancelled'; // Job was cancelled
Pipeline Domains#
type PipelineDomain =
| 'general' // All-purpose motion capture
| 'yoga' // Yoga poses and slow movements
| 'fitness' // Exercise and workout tracking
| 'dance' // Dance and choreography
| 'martial-arts' // Combat sports
| 'sports'; // Athletic motion
Quality Presets#
type QualityPreset =
| 'draft' // Fast, lower quality
| 'standard' // Balanced
| 'high' // High quality
| 'ultra'; // Best quality
Job Priority#
type JobPriority =
| 'critical' // Process immediately
| 'high' // High priority
| 'normal' // Default priority
| 'low' // Low priority
| 'background'; // Process when idle
Error Handling#
const result = await client.submitJob(request);
if (!result.success) {
const error = result.error;
switch (error.code) {
case 'INVALID_INPUT':
console.error('Invalid video format:', error.message);
break;
case 'QUOTA_EXCEEDED':
console.error('Processing quota exceeded');
break;
case 'UNAUTHORIZED':
console.error('Invalid API key');
break;
default:
console.error('Unexpected error:', error.message);
}
return;
}
// Success path
const job = result.data;
Best Practices#
1. Reuse Client Instances#
Create a single client instance and reuse it across your application:
// client.ts
import { createClient } from '@aja/motion-pipeline-sdk';
export const ajaClient = createClient({
baseUrl: process.env.AJA_API_URL!,
auth: {
type: 'api-key',
apiKey: process.env.AJA_API_KEY!,
},
});
2. Handle All Error Cases#
Always check result.success before accessing data:
const result = await client.getJob(id);
if (!result.success) {
// Handle error appropriately
throw new Error(result.error.message);
}
// Now TypeScript knows result.data exists
const job = result.data;
3. Use Webhooks for Production#
For production workloads, use webhooks instead of polling:
await client.submitJob({
input: { type: 'url', url: videoUrl, filename: 'video.mp4' },
pipelineConfig: configId,
options: {
webhook: {
url: 'https://your-app.com/webhooks/aja',
events: ['completed', 'failed'],
},
},
});
4. Stream Progress for Long Jobs#
For long-running jobs, use streaming instead of polling:
const unsubscribe = client.streamJobProgress(jobId, {
onProgress: (event) => updateUI(event.data.progress),
onComplete: (event) => handleComplete(event.data),
onError: (event) => handleError(event.data),
});