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:
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:
{
"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#
{
"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#
{
"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#
{
"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#
{
"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)#
{
"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#
{ "priority": "high" }
Priority values: critical, high, normal, low, background
Cancel Job Request#
{ "reason": "User cancelled from UI" }
Batch Operations Request#
{
"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#
{
"outputIndex": 0,
"format": "fbx",
"expiresInSec": 3600
}
Download Response#
{
"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#
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#
{
"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#
{
"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#
{
"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#
{
"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#
{
"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 |