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