Eve library

Aja Motion Pipeline SDK for Python

Other

Revision 1

On this page

A comprehensive Python SDK for the Aja Motion Pipeline Service, providing type-safe access to video-to-motion processing, batch operations, data science workflows, and model training integration.

Features#

  • Full API Coverage: Access all pipeline operations including configuration management, job submission/monitoring, streaming, and downloads
  • Type-Safe Interfaces: Comprehensive type hints with Pydantic models
  • Async Support: Full async/await support with AsyncMotionPipelineClient
  • Batch Processing: Process multiple videos efficiently with configurable parallelism, retries, and rate limiting
  • Jupyter Integration: Interactive widgets, progress displays, and visualization tools for notebooks
  • Data Science Utilities: DataFrame conversion, statistical analysis, and visualization helpers
  • Model Training Integration: PyTorch datasets, data loaders, and training helpers for motion models

Installation#

bash
# Basic installation
pip install aja-motion-pipeline

# With Jupyter support
pip install aja-motion-pipeline[jupyter]

# With data science tools
pip install aja-motion-pipeline[datascience]

# With model training support
pip install aja-motion-pipeline[training]

# Everything
pip install aja-motion-pipeline[all]

Quick Start#

Basic Usage#

python
from lilith_motion_pipeline import (
    MotionPipelineClient,
    SDKConfig,
    AuthConfig,
    AuthType,
    JobSubmitRequest,
    VideoInputSource,
    InputSourceType,
)

# Create client
client = MotionPipelineClient(
    SDKConfig(
        base_url="https://api.aja.example.com",
        auth=AuthConfig(type=AuthType.API_KEY, api_key="your-key"),
    )
)

# Submit a job
result = client.submit_job(
    JobSubmitRequest(
        input=VideoInputSource(
            type=InputSourceType.URL,
            url="https://example.com/video.mp4",
        ),
        pipeline_config="yoga-high",
    )
)

if result.success:
    print(f"Job submitted: {result.data.job_id}")

Fluent Builder Pattern#

python
result = (
    client.job_builder()
    .from_url("https://example.com/video.mp4")
    .with_config("yoga-high")
    .priority(JobPriority.HIGH)
    .tags("demo", "yoga")
    .submit()
)

Submit and Wait#

python
result = client.submit_and_wait(
    request,
    poll_interval_ms=2000,
    timeout_ms=3600000,
    on_progress=lambda job: print(f"Progress: {job.progress}%"),
)

if result.success:
    job = result.data
    if job.status == JobStatus.COMPLETED:
        print(f"Job completed! Quality score: {job.result.quality_metrics.overall_score}")

Async Client#

python
import asyncio
from lilith_motion_pipeline import AsyncMotionPipelineClient

async def main():
    async with AsyncMotionPipelineClient(config) as client:
        result = await client.submit_job(request)

        # Stream progress
        async for event in client.stream_job_progress(result.data.job_id):
            if event.type == StreamEventType.JOB_PROGRESS:
                print(f"Progress: {event.data['progress']}%")

asyncio.run(main())

Batch Processing#

python
from lilith_motion_pipeline.batch import BatchProcessor, BatchConfig

processor = BatchProcessor(client)

summary = processor.process_urls(
    urls=[
        "https://example.com/video1.mp4",
        "https://example.com/video2.mp4",
        "https://example.com/video3.mp4",
    ],
    pipeline_config="yoga-high",
    config=BatchConfig(
        max_concurrent=5,
        retry_failed=True,
    ),
    wait_for_completion=True,
)

print(f"Processed {summary.succeeded}/{summary.total} videos")
print(f"Success rate: {summary.success_rate:.1f}%")

Jupyter Notebook Integration#

python
from lilith_motion_pipeline.jupyter import (
    ProgressDisplay,
    JobCard,
    create_job_browser,
)

# Track job with live progress
progress = ProgressDisplay()
job = progress.track_job(client, job_id)

# Display job as card
JobCard(job).display()

# Interactive job browser
browser = create_job_browser(client)
display(browser)

Data Science Utilities#

python
from lilith_motion_pipeline.data_science import (
    jobs_to_dataframe,
    calculate_job_statistics,
    plot_quality_metrics_comparison,
)

# Convert to DataFrame
df = jobs_to_dataframe(jobs)

# Calculate statistics
stats = calculate_job_statistics(jobs)
print(f"Success rate: {stats.success_rate:.1f}%")
print(f"Average quality: {stats.avg_quality_score:.2f}")

# Visualize
fig = plot_quality_metrics_comparison(jobs)
fig.savefig("quality_comparison.png")

Model Training Integration#

python
from lilith_motion_pipeline.training import (
    MotionDataLoader,
    MotionDataset,
    TrainingHelper,
    TrainingConfig,
)
from torch.utils.data import DataLoader

# Load motion data from jobs
loader = MotionDataLoader(client)
sequences = loader.load_from_jobs(completed_jobs)

# Create PyTorch dataset
dataset = MotionDataset(
    sequences,
    max_frames=300,
    normalize=True,
    augment=True,
)

# Training
helper = TrainingHelper(TrainingConfig(
    batch_size=32,
    learning_rate=1e-4,
    epochs=100,
))

train_loader, val_loader = helper.prepare_data(sequences)

Error Handling#

python
from lilith_motion_pipeline import (
    SDKError,
    is_retryable_error,
    is_not_found_error,
)

try:
    result = client.get_job(job_id)
    if not result.success:
        print(f"Error: {result.error.message}")
except SDKError as e:
    if is_retryable_error(e):
        print("Retrying...")
    elif is_not_found_error(e):
        print("Job not found")

Configuration Options#

python
SDKConfig(
    base_url="https://api.aja.example.com",
    auth=AuthConfig(
        type=AuthType.API_KEY,
        api_key="your-key",
    ),
    tenant_id="your-tenant",
    user_id="your-user",
    timeout_ms=30000,
    retry=RetryConfig(
        max_attempts=3,
        initial_delay_ms=1000,
        max_delay_ms=30000,
        multiplier=2.0,
    ),
    debug=True,
)

Authentication Methods#

API Key#

python
auth=AuthConfig(type=AuthType.API_KEY, api_key="your-key")

Bearer Token#

python
auth=AuthConfig(type=AuthType.BEARER, bearer_token="your-token")

OAuth2 Client Credentials#

python
auth=AuthConfig(
    type=AuthType.OAUTH2,
    oauth2=OAuth2Config(
        token_url="https://auth.example.com/oauth/token",
        client_id="your-client-id",
        client_secret="your-client-secret",
        scopes=["pipeline:read", "pipeline:write"],
    ),
)

License#

MIT