Cosmos Documentation

Cosmos is Polli's media processing toolkit for COSM camera data. It is designed to be safe for both humans and automation:

• two CLIs (cosmos, squarecrop)
• one SDK (cosmos.sdk.*)
• deterministic provenance artifacts for every real output

Start with the workflow you need

Ingest raw camera output into MP4 clips

• Read: Ingest User Guide
• Validate source layout: Input Structure
• Command reference: cosmos CLI

Create square/rect views and visual QA previews

• Read: Squarecrop User Guide
• Commands: squarecrop CLI
• Preview output contracts: Provenance

Optimize existing MP4s for web delivery

Use cosmos optimize run when you need faststart relocation, optional transcode transforms, and reproducible optimize provenance.

• Command details: cosmos CLI
• Encoder fallback policy: Encoder Behavior

Canonical command quickstart

cosmos --help
cosmos ingest run --help
cosmos crop run --help
cosmos optimize run --help
cosmos crop preview --help
squarecrop --help

Provenance is a first-class contract

Cosmos writes run-level and artifact-level JSON sidecars so downstream systems can audit exactly how each file was produced.

• Overview and join keys: Provenance
• Schemas: see the Reference section below

Agent-friendly usage (Cosmos skill)

The canonical Cosmos skill package is versioned in-repo and should be used when planning or shipping CLI/SDK/provenance changes.

• Skill entrypoint: skills/cosmos/SKILL.md
• API surface reference: skills/cosmos/references/api-surfaces.md
• Maintenance ritual: skills/cosmos/references/maintenance-ritual.md

For a docs-local summary, see Cosmos Skill.

Reference map

• CLI references: cosmos CLI, squarecrop CLI
• SDK API entry points: SDK
• Platform encoder behavior: Encoder Behavior
• Schemas:
• ingest_run.v1.json
• clip.v1.json
• crop_run.v1.json
• view.v1.json
• optimize_run.v1.json
• optimized.v1.json
• crop_preview_run.v1.json
• crop_preview_plan.v1.json