Eve library

Aja Domain API Reference

Guide

Revision 1

On this page

Aja is the motion capture and animation domain of the Oshun platform. It provides two backend services for processing video into motion data, retargeting motion between skeletons, and orchestrating multi-stage pipeline jobs.

Service Framework Default Port Purpose
svc-motion-pipeline Fastify 8090 Pipeline orchestration, job management, delivery
svc-motion-ai Hono 3040 AI-powered motion processing (V2M, retargeting)

There is also a companion CLI tool (apps/aja/cli) and a reference video service (apps/aja/svc-reference-video) for video library management.


Common Patterns#

Authentication#

Both services accept tenant and user identity via headers:

text
X-Tenant-ID: tenant_abc
X-User-ID: usr_123

The motion pipeline service uses these to scope job visibility and ownership.

Error Format#

Both services return errors with code and message fields:

json
{
  "code": "JOB_NOT_FOUND",
  "message": "Job not found"
}

1. Motion Pipeline Service (svc-motion-pipeline)#

Base URL: /v1/pipeline

Source: apps/aja/svc-motion-pipeline/src/app.ts

The motion pipeline service orchestrates multi-stage motion processing jobs. Each job progresses through configurable pipeline stages (video preprocessing, pose estimation, temporal smoothing, format conversion, quality analysis, etc.) and supports real-time progress streaming via SSE, webhook callbacks, and polling.

1.1 Health & Statistics#

Method Path Description
GET /health Service health with component status
GET /v1/pipeline/stats Queue statistics (waiting, active, completed, failed)

Health Response#

json
{
  "status": "healthy",
  "components": {
    "jobManager": {
      "name": "Job Manager",
      "status": "healthy",
      "lastCheck": "..."
    },
    "webhookService": {
      "name": "Webhook Service",
      "status": "healthy",
      "lastCheck": "..."
    },
    "configRepository": {
      "name": "Configuration Repository",
      "status": "healthy",
      "lastCheck": "..."
    }
  },
  "uptimeSeconds": 86400,
  "lastCheck": "2026-02-14T12:00:00.000Z"
}

1.2 Pipeline Configuration#

Configurations define the stages, quality presets, timeouts, and output format for a pipeline run.

Method Path Description
GET /v1/pipeline/configs List configurations
GET /v1/pipeline/configs/:configId Get configuration by ID
GET /v1/pipeline/configs/by-name/:name Get configuration by name
POST /v1/pipeline/configs Create from JSON
POST /v1/pipeline/configs/yaml Create from YAML definition
GET /v1/pipeline/configs/:configId/yaml Export configuration as YAML
DELETE /v1/pipeline/configs/:configId Delete a configuration
GET /v1/pipeline/presets List all quality presets

List Configs Query Parameters#

Parameter Type Description
domain string Filter by domain (see below)
qualityPreset string Filter by quality preset

Pipeline Domains#

Domain Description
yoga Yoga pose and flow sequences
fitness General fitness and exercise
dance Dance choreography
martial-arts Martial arts forms and techniques
general General-purpose motion capture

Quality Presets#

Preset Description
draft Fast processing, lower accuracy, for previews
standard Balanced speed and quality for production use
high High accuracy with advanced filtering
ultra Maximum quality with all enhancement stages enabled

Each preset affects the number and configuration of pipeline stages (e.g., whether physics refinement, super-resolution, and style transfer stages are enabled).

Create Configuration Request#

json
{
  "name": "yoga-high",
  "description": "High-quality yoga motion capture pipeline",
  "domain": "yoga",
  "qualityPreset": "high",
  "globalTimeoutMs": 3600000,
  "failFast": false,
  "metadata": {
    "team": "motion-team"
  }
}

Create Configuration from YAML#

json
{
  "yaml": "name: custom-pipeline\ndomain: general\nqualityPreset: standard\nstages:\n  - name: preprocessing\n    enabled: true\n    timeoutMs: 60000\n  - name: pose-estimation\n    enabled: true\n    timeoutMs: 300000\n"
}

1.3 Job Management#

Jobs are the primary work unit. A job runs a pipeline configuration against input data and produces motion data outputs.

Method Path Description
POST /v1/pipeline/jobs Submit a new job
GET /v1/pipeline/jobs List jobs (scoped to tenant)
GET /v1/pipeline/jobs/:jobId Get job status (polling endpoint)
POST /v1/pipeline/jobs/:jobId/cancel Cancel a job
POST /v1/pipeline/jobs/:jobId/retry Retry a failed job
PATCH /v1/pipeline/jobs/:jobId/priority Update job priority
POST /v1/pipeline/jobs/batch Batch operations on multiple jobs

Submit Job Request#

json
{
  "pipelineConfig": "yoga-high",
  "input": {
    "videoUrl": "https://storage.example.com/videos/session-001.mp4",
    "frameRate": 30,
    "startTimeSec": 0,
    "endTimeSec": 120
  },
  "options": {
    "priority": "normal",
    "callbackUrl": "https://hooks.example.com/motion-complete",
    "metadata": {
      "sessionId": "sess_001",
      "instructorId": "inst_042"
    }
  },
  "webhook": {
    "url": "https://hooks.example.com/motion-events",
    "secret": "whsec_...",
    "events": [
      "job.queued",
      "job.started",
      "job.progress",
      "job.completed",
      "job.failed"
    ]
  }
}

The pipelineConfig field accepts either a configuration ID, a configuration name (string), or an inline configuration object.

Submit Job Response (202 Accepted)#

json
{
  "jobId": "job_abc123",
  "status": "pending",
  "createdAt": "2026-02-14T12:00:00.000Z",
  "pollUrl": "/v1/pipeline/jobs/job_abc123",
  "streamUrl": "/v1/pipeline/jobs/job_abc123/stream"
}

Job List Query Parameters#

Parameter Type Description
status string Comma-separated status filter
limit number Max results
offset number Skip count

Update Priority Request#

json
{ "priority": "high" }

Priority values: critical, high, normal, low, background

Cancel Job Request#

json
{ "reason": "User cancelled from UI" }

Batch Operations Request#

json
{
  "operation": "cancel",
  "jobIds": ["job_001", "job_002", "job_003"],
  "reason": "Batch cancellation"
}

1.4 Job Outputs & Downloads#

Method Path Description
GET /v1/pipeline/jobs/:jobId/outputs List available output files
POST /v1/pipeline/jobs/:jobId/download Generate a signed download URL

Output listing is only available for completed jobs. Each output includes format, file size, and checksum information.

Download Request#

json
{
  "outputIndex": 0,
  "format": "fbx",
  "expiresInSec": 3600
}

Download Response#

json
{
  "url": "https://storage.example.com/outputs/job_abc/output.fbx?...",
  "expiresAt": "2026-02-14T13:00:00.000Z",
  "sizeBytes": 1048576,
  "checksum": "sha256:abc123..."
}

1.5 SSE Progress Streaming#

Method Path Description
GET /v1/pipeline/jobs/:jobId/stream SSE progress stream
GET /v1/pipeline/streams/stats Active connection count

The SSE endpoint opens a persistent connection and streams events as the job progresses. Only active jobs (pending, queued, running) can be streamed.

SSE Event Types#

Event Type Description
connected Initial connection with job status
progress Overall progress update
stage_update Individual stage started/completed/failed
completion Job completed with results and stats
error Job failed with error details

SSE Progress Event Example#

text
data: {"type":"progress","jobId":"job_abc","percentage":45,"currentStage":"pose-estimation","stagePercentage":72,"message":"Processing pose-estimation..."}

1.6 Webhook Management#

Method Path Description
GET /v1/pipeline/jobs/:jobId/webhooks List webhook deliveries for job
GET /v1/pipeline/webhooks/:deliveryId Get delivery status
POST /v1/pipeline/webhooks/:deliveryId/retry Retry a failed delivery
GET /v1/pipeline/webhooks/stats Webhook delivery statistics

Webhook Event Types#

Event Trigger
job.queued Job enters the queue
job.started Processing begins
job.progress At 25%, 50%, 75% completion (throttled)
job.completed Job finished successfully
job.failed Job failed with error
job.cancelled Job was cancelled
stage.started Pipeline stage begins
stage.completed Pipeline stage finishes
stage.failed Pipeline stage fails

Webhook Payload Structure#

json
{
  "event": "job.completed",
  "jobId": "job_abc123",
  "timestamp": "2026-02-14T12:05:00.000Z",
  "data": {
    "result": {
      "primaryOutput": {
        "format": "fbx",
        "path": "/outputs/job_abc/output.fbx",
        "sizeBytes": 1048576,
        "checksum": "sha256:..."
      }
    },
    "stats": {
      "totalDurationMs": 45000,
      "stagesCompleted": 6,
      "stagesFailed": 0
    }
  }
}

2. Motion AI Service (svc-motion-ai)#

Base URL: /api/v1

Default Port: 3040

Source: apps/aja/svc-motion-ai/src/app.ts

The motion AI service provides stateless AI-powered motion processing endpoints. Each endpoint processes a request synchronously and returns results. For long operations, the pipeline service wraps these calls as pipeline stages.

2.1 Health#

Method Path Description
GET /health Health check

2.2 Video-to-Motion#

Extracts motion data from video input by running video preprocessing, pose estimation, keypoint normalization, and temporal processing.

Method Path Description
POST /api/v1/video-to-motion/process Process video to motion

Request Body#

json
{
  "videoUrl": "https://storage.example.com/videos/session.mp4",
  "options": {
    "frameRate": 30,
    "startTime": 0,
    "endTime": 60,
    "poseModel": "mediapipe-holistic",
    "outputFormat": "bvh",
    "smoothing": {
      "enabled": true,
      "windowSize": 5,
      "method": "savitzky-golay"
    }
  }
}

Response#

Returns extracted motion data with joint positions, rotations, and quality metrics.

2.3 Motion Retargeting#

Transfers motion from one skeleton topology to another, adjusting for bone length differences and joint mapping.

Method Path Description
POST /api/v1/retargeting/retarget Retarget motion between skeletons

Request Body#

json
{
  "sourceMotion": { "format": "bvh", "data": "..." },
  "sourceSkeleton": { "type": "mixamo", "jointCount": 65 },
  "targetSkeleton": { "type": "unreal-mannequin", "jointCount": 67 },
  "options": {
    "preserveFootContact": true,
    "adjustHipHeight": true,
    "ikEnabled": true
  }
}

2.4 Skeletal Animation#

Generates or processes skeletal animation data for a target skeleton definition.

Method Path Description
POST /api/v1/skeletal/animate Animate a skeleton

Request Body#

json
{
  "skeleton": {
    "type": "custom",
    "joints": [...],
    "hierarchy": [...]
  },
  "animation": {
    "type": "procedural",
    "params": {
      "style": "walk",
      "speed": 1.2,
      "direction": [0, 0, 1]
    }
  },
  "outputFormat": "fbx"
}

2.5 Video Analysis#

Analyzes video content for motion quality, scene detection, and movement classification without full motion extraction.

Method Path Description
POST /api/v1/analysis/analyze Analyze video for motion data

Request Body#

json
{
  "videoUrl": "https://storage.example.com/videos/reference.mp4",
  "analysisTypes": [
    "motion-quality",
    "scene-detection",
    "movement-classification"
  ],
  "options": {
    "sampleRate": 10,
    "confidenceThreshold": 0.8
  }
}

Additional Services#

Reference Video Service (svc-reference-video)#

Source: apps/aja/svc-reference-video/src/

A library management service for reference videos used in motion capture workflows. Provides:

  • Video Ingestion -- Upload and store reference videos
  • Metadata Extraction -- Auto-extract duration, resolution, codec
  • Scene Detection -- Identify scene boundaries
  • Video Categorization -- Classify by movement type, domain
  • Video Search -- Full-text and metadata search
  • Annotation -- Timestamp-based annotations
  • Collaboration -- Shared video collections and comments

CLI Tool (cli)#

Source: apps/aja/cli/src/

A command-line interface for interacting with the Aja services:

Command Description
process Submit a video for motion processing
jobs List and manage pipeline jobs
config Manage pipeline configurations
convert Convert between motion data formats
inspect Inspect motion data files
health Check service health
debug Debug utilities