Oscar CLI

Oscar CLI is the automation surface for Oscar. It is meant for creators, operators, and agents that need repeatable media workflows across AutoEdit, Create, Moments, short video, campaign generation, visualizers, and batch runs.

The CLI is not a separate product engine. It calls the same Oscar SDK/runtime contracts used by the web app. Local media execution stays local; account policy, plan checks, and usage metering stay server-authoritative.

Agent Quickstart

Use this path when an agent needs to understand and unlock Oscar quickly.

npm install -g @oscareditor/cli

oscar auth login
oscar auth status
oscar workflows
oscar operations
oscar capabilities

Then inspect exact schemas before calling a workflow:

oscar workflow-schema moments
oscar workflow-schema render-composition-final
oscar workflow-schema finalize-voice

For machine use, prefer JSON:

oscar --json workflows
oscar --json workflow-schema moments

For task-oriented examples, see AGENT_PLAYBOOK.md.

Install

npm install -g @oscareditor/cli
oscar --help

Requirements:

• Node.js 20 or newer.
• An Oscar account for counted local work.
• Playwright/Chromium. The published package depends on playwright; if your npm environment skips browser downloads, run npx playwright install chromium.

Authentication

Counted local workflows require an Oscar account. The normal path opens Oscar in your browser, signs you in, and stores CLI credentials locally.

oscar auth login
oscar auth status

Useful checks:

oscar capabilities
oscar workflows

Runtime Model

Oscar CLI supports two local execution paths:

• local-direct: default beta path. Starts Oscar's packaged local web runtime, queue bridge, and headless worker automatically. No project repo or dev server is required.
• local-runtime: connects to an already-running bridge host for diagnostics and advanced local setups.

The beta npm package includes the runtime assets needed for reliable first-run local execution: Oscar web worker code, audio FFmpeg core, full video FFmpeg core, ASR model, speech enhancer model, and bundled visualizer/Moments media. Small protected audio runtimes are installed lazily after account verification when a protected workflow first needs them.

Bridge environment:

export OSCAR_BRIDGE_URL=http://127.0.0.1:4318
export OSCAR_BRIDGE_TOKEN=...

Diagnostics:

oscar bootstrap
oscar jobs --backend local-runtime
oscar bridge-worker-headless --bridge-url "$OSCAR_BRIDGE_URL" --token "$OSCAR_BRIDGE_TOKEN" --web-url http://127.0.0.1:5173

Discovery Commands

These commands are the capability map for agents:

oscar workflows
oscar workflow-schema <workflowId>
oscar operations
oscar capabilities
oscar video-capabilities
oscar music-runtime-capabilities

workflows describes higher-level product workflows. operations lists lower-level AutoEdit actions. workflow-schema is the safest way to discover the required payload before generating JSON for a command.

AutoEdit Audio

Use AutoEdit audio commands for cleanup, finalization, repair, loudness, and creative voice/music processing.

Primary workflows:

oscar finalize-voice voice.wav --output voice.final.wav --metadata-out voice.json
oscar finalize-music mix.wav --output mix.final.wav --metadata-out mix.json
oscar mixfix audio.wav --output fixed.wav
oscar auto-edit-audio audio.wav --output edited.wav

Common actions:

oscar measure-lufs audio.wav --metadata-out lufs.json
oscar normalize-audio audio.wav --output normalized.wav
oscar make-loud audio.wav --output loud.wav
oscar dialog-leveler dialogue.wav --output leveled.wav
oscar balance-audio audio.wav --output balanced.wav
oscar make-voice-pop voice.wav --output pop.wav
oscar ai-denoise noisy.wav --output clean.wav
oscar de-esser voice.wav --output deessed.wav
oscar de-reverb voice.wav --output dry.wav
oscar voice-clarity voice.wav --output clear.wav
oscar remove-hiss noisy.wav --output hissless.wav
oscar clean-resonances audio.wav --output deresonated.wav
oscar de-hum hum.wav --output dehum.wav
oscar click-pop-repair clicks.wav --output repaired.wav

Creative audio:

oscar graphic-eq audio.wav --params '{"bands":[{"frequency":1000,"gainDb":1.5,"q":1}]}' --output eq.wav
oscar more-stereo audio.wav --output wide.wav
oscar pitchshift audio.wav --params '{"semitones":2}' --output pitched.wav
oscar reverse audio.wav --output reversed.wav
oscar lo-fiizer audio.wav --output lofi.wav
oscar movement audio.wav --output moving.wav
oscar loopify audio.wav --output loop.wav
oscar chop-flip audio.wav --output chopped.wav
oscar speech-enhancer voice.wav --output enhanced.wav
oscar voice-styles voice.wav --output styled.wav
oscar voice-realism voice.wav --output natural.wav
oscar tone-match audio.wav --output matched.wav
oscar make-ambient-music audio.wav --output ambient.wav
oscar auto-fades audio.wav --output fades.wav
oscar auto-trim-audio audio.wav --output trimmed.wav

Generic operation runner:

oscar run normalize-audio input.wav --output normalized.wav
oscar run <operationId> <inputPath> --params '{"amount":60}' --output out.wav

AutoEdit Video

Use these for video finalization, trimming, reframing, muxing, and short-form extraction.

oscar inspect-media input.mp4 --output media.json
oscar inspect-video-rich input.mp4 --output video-rich.json
oscar transcode-video input.mov --output output.mp4
oscar trim-video-exact input.mp4 --params '{"startSec":1,"endSec":8}' --output clip.mp4
oscar auto-trim-fast input.mp4 --output trimmed.mp4
oscar make-reel input.mp4 --output reel.mp4
oscar reframe-vertical input.mp4 --output vertical.mp4
oscar mux-video-audio input.mp4 track.wav --output muxed.mp4
oscar concat-video clip-a.mp4 clip-b.mp4 --output combined.mp4
oscar transcribe input.mp4 --format json --output transcript.json
oscar edit-video input.mp4 --find "competitive advantage, more differentiation" --output clip.mp4 --metadata-out clip.json
oscar shorts-factory input.mp4 --mode render --output shorts.mp4

edit-video --find is the direct text-to-clip path. It transcribes the video, matches the spoken phrase against timed words, pads the range, and exports the matched clip.

transcribe outputs text plus timestamped cues/words, so agents can search a video or audio file and then call trim-video-exact on custom matching time ranges. Use --format txt, --format srt, or --format vtt when the next tool wants plain text or caption files.

shorts-factory --mode preview is useful for clip analysis and JSON planning. Use --mode render when the agent needs an actual video file.

Oscar Moments

Turn a folder of images into a music-synced social video.

oscar moments \
  --assets-dir ./photos \
  --vibe alive \
  --music auto \
  --aspect 9:16 \
  --duration 15 \
  --output out.mp4 \
  --metadata-out out.json

Vibes:

• alive
• cool
• cinematic
• retro

Music can be auto or a local audio file path.

Campaign Agent

Campaign commands generate, score, improve, and rank campaign-style creative variants.

oscar campaign-run --params-file campaign.json --output campaign-result.json
oscar campaign-generate --params-file campaign.json --output variants.json
oscar campaign-score --params-file variant.json --output score.json
oscar campaign-autofix --params-file variant.json --output fixed.json
oscar campaign-rank --params-file variants.json --output ranked.json

Campaign run can ingest local assets:

oscar campaign-run \
  --params-file campaign.json \
  --visual-file hero.mov \
  --audio-file track.wav \
  --assets-dir ./assets \
  --output campaign-result.json

Static preview export:

oscar campaign-static-preview campaign-result.json ./previews --width 1080 --height 1920

Short Video Maker

Short video commands compose and render music-video.v1 compositions.

oscar compose-short --params-file compose.json --output composition.json
oscar render-short-preview --params-file composition.json --output preview.mp4 --metadata-out preview.json
oscar render-short-final --params-file composition.json --output final.mp4 --metadata-out final.json

For direct JSON compositions, pass a music-video.v1 payload to render-short-preview or render-short-final.

Minimal compose.json with a local audio file and image background:

{
  "audioPath": "./track.wav",
  "backgroundPath": "./cover.png",
  "intent": "promo",
  "aspect": "9:16",
  "durationSec": 10,
  "sceneCount": 4,
  "sceneTexts": ["New drop", "Built for creators", "Out now"]
}

Audio Visualizer

oscar visualizer-preview track.wav cover.png --params '{"lengthPreset":10,"aspect":"9:16","resolution":"720p"}' --output preview.mp4
oscar visualizer-render track.wav cover.png --params '{"lengthPreset":15,"aspect":"9:16","resolution":"1080p"}' --output final.mp4 --metadata-out visualizer.json
oscar analyze-audio-markers track.wav --output markers.json --max-duration-sec 30

Inspection

oscar inspect-media media.mp4 --output media.json
oscar inspect-audio-rich audio.wav --output audio-rich.json
oscar inspect-video-rich video.mp4 --output video-rich.json

Batch Automation

Use batch when an agent needs repeatable work across many files.

oscar batch-run --manifest batch.json --output-dir ./exports --metadata-out batch-summary.json

Batch is plan-gated. Use oscar capabilities to check batchEnabled.

Asset Utilities

oscar export-asset <assetId> ./asset.wav --format wav
oscar cleanup-asset <assetId>

These are mostly useful when composing lower-level SDK/bridge flows.

Output And Auditing

Use --metadata-out on render/finalization commands whenever an agent needs a durable audit trail.

oscar finalize-voice voice.wav --output voice.final.wav --metadata-out voice.summary.json
oscar moments --assets-dir ./photos --output moment.mp4 --metadata-out moment.summary.json

Use --json for command summaries:

oscar --json workflow-schema moments

Product Surface Map

| Product surface | CLI entry points | | --- | --- | | AutoEdit audio | finalize-voice, finalize-music, mixfix, audio action commands, run <operationId> | | AutoEdit video | transcode-video, trim-video-exact, auto-trim-fast, make-reel, reframe-vertical, mux-video-audio, concat-video, transcribe, edit-video, shorts-factory | | Oscar Moments | moments | | Campaign Agent | campaign-run, campaign-generate, campaign-score, campaign-autofix, campaign-rank, campaign-static-preview | | Short Video Maker | compose-short, render-short-preview, render-short-final | | Audio Visualizer | visualizer-preview, visualizer-render, analyze-audio-markers | | Automation | batch-run, workflows, workflow-schema, operations, jobs |

Troubleshooting

oscar auth status
oscar bootstrap
oscar capabilities

Common issues:

• OSCAR_CLI_USAGE_SYNC_FAILED: reconnect with oscar auth login, then retry.
• OSCAR_CLI_LEASE_FAILED: reconnect with oscar auth login, then verify your plan has access to the workflow.
• Bridge not ready: start or connect a bridge worker and verify OSCAR_BRIDGE_URL/OSCAR_BRIDGE_TOKEN.
• Batch processing is not available: current plan does not allow batch.

For browser-backed local rendering, avoid incognito/private browser sessions because FFmpeg/WebAssembly workers can be restricted.