@soloom/soloom
v0.1.7
Published
Open-source, agent-driven video editing and production environment.
Readme
About
Soloom is a general-purpose video editing CLI for Codex, Claude Code, and other external coding agents. Bring your own agent, write the production code, and make any kind of video: a polished original, a high-performing short, or a faithful reference remake. The agent can read a reference, use your footage, call configured media providers, author captions and Motion Graphs, and arrange the result on a real editable timeline.
The project is deliberately open-ended. Soloom does not prescribe a remix template or a fixed production script. Your agent decides what the piece means and how it should feel; Soloom supplies the media facts, timeline primitives, execution records, browser editor, and export path needed to make that decision tangible. You can review the actual cut in the browser, adjust it by hand, and continue editing after the agent finishes.
Every generated result stays inspectable and editable. A rendered file is an output, not the end of the project: the source program, assets, provider operations, timeline, and result remain connected.
Soloom is designed to be installed once and used from any project directory. The Agent Skill explains the capabilities to Codex, Claude Code, Cursor, Gemini CLI, and other compatible agents; the CLI and runtime do the actual work. The Soloom repository itself is not required in a user's video project.
What you can make
- Edit supplied video, audio, images, captions, and Motion Graph layers.
- Turn a reference video into reusable timing, speech, visual, and composition evidence.
- Use an ordinary npm/ESM project as a code-authored timeline.
- Generate video, speech, music, and transcripts through the configured Gateway or another compatible service.
- Create multiple independent variants from one program without copying a fixed workflow.
- Open the result in the browser editor, change any layer, and export it again.
- Export the same timeline as a finished video or as an interchange project for Final Cut Pro, Premiere Pro, and DaVinci Resolve.
Common starting points include:
- Reference-led remakes that preserve pacing, caption rhythm, reveals, and layer relationships while changing the story, speaker, product, or language.
- High-performing short-form variations with new hooks, rankings, CTAs, captions, music, and generated B-roll.
- Original explainers, product launches, podcast clips, music-led edits, social ads, and motion-graphics pieces.
- Human-finished edits where an Agent prepares the first cut and an editor takes over in the browser or in a traditional post-production tool.
How it works
Your agent and its project code
|
v
Evidence, assets, and provider results
|
v
Soloom program and timeline
|
v
Editable browser project
|
v
Preview and exportThe Soloom CLI and runtime execute trusted local Node.js programs. The browser never evaluates arbitrary project code. It receives a verified, portable timeline and the artifact identities produced by the runtime.
Quick start
Soloom requires Node.js 22.14.0 or newer.
npm install --global @soloom/soloom
soloom --version
soloom doctor
soloom skill manifest
soloom project init ./my-video/project.yaml --id my-videoFor a one-off invocation:
npx @soloom/soloom doctorsoloom doctor checks Node.js, Chromium, HyperFrames, Mediabunny, WebCodecs, the local runtime bundles, and the real headless export path. Set SOLOOM_CHROME when Chromium is not available on PATH.
Use Soloom with your agent
Soloom is agent-agnostic. Install its Skill once, then start a session in any video project directory:
npx skills add aixcut/soloom -gThe standard Skills CLI owns host detection, agent-specific directories, project versus global scope,
updates, and collision handling. Use its --agent option only when you need to target a specific
host, for example npx skills add aixcut/soloom -g --agent claude-code. Soloom does not duplicate
that installer or maintain separate copies for Codex, Claude Code, Cursor, and Gemini. Install the
executable separately with npm install --global @soloom/soloom when the soloom command is not
already available.
The Skill is a capability map, not a fixed workflow. It teaches the agent how to inspect references, discover the deployed Gateway models, author a program, run a build, open the editable result, and export the finished timeline. The same project can be used from Codex, Claude Code, Cursor, Gemini CLI, or another host that supports agent skills.
Example requests:
Create three short-form variants from ./reference.mp4. Keep the hook timing and caption rhythm, replace the speaker and product, and leave each result editable.Turn this product brief and these clips into a 30-second launch video. Use the configured Gateway for voice and B-roll, then show me the editable timeline before exporting.The Agent writes or updates the project program. Soloom executes it, records the actual provider and render results, and keeps the browser timeline available for human direction.
Author a video with an agent
Create a normal npm project in the video project directory. There is no required package.yaml and no Soloom-specific source language.
my-video/
|-- package.json
|-- program.mjs
|-- project.yaml
`-- assets/The program can use its own dependencies and helper modules. It returns a timeline or a full authoring object through the public SDK:
import { withTimeline } from '@soloom/soloom/program';
export default withTimeline(({ timeline, runtime }) => {
const hero = runtime.assets.find((asset) => asset.id === 'artifact:hero');
if (!hero) throw new Error('hero asset is missing');
timeline
.track('picture', 'video', { stackOrder: 0 })
.track('captions', 'text', { stackOrder: 1 })
.video('hero', {
trackId: 'picture',
mediaId: hero.mediaId,
fileRevision: hero.fileRevision,
startMs: 0,
endMs: 5000,
})
.caption('title', {
trackId: 'captions',
text: 'A new cut',
startMs: 500,
endMs: 2500,
});
return { timeline };
});Check, preview, or build the project:
soloom program check ./program --project ./my-video/project.yaml
soloom program run ./program --project ./my-video/project.yaml --out ./program-output.yaml
soloom program build ./program --project ./my-video/project.yaml --live --wait
soloom history ./my-video/project.yamlThe same commands accept a project directory. Soloom resolves its package.json, keeps its npm exports and dynamic imports, and runs it in the trusted Node harness. The program chooses the tracks, timing, assets, captions, Motion Graphs, and variants; the runtime connects the result to Build, Result, Artifact, preview, and export.
Providers and Gateway
The optional @soloom/gateway service keeps upstream provider keys on the server and exposes one model-aware API for speech recognition, speech synthesis, image generation, video generation, and media operations. Soloom asks the Gateway what capabilities are enabled instead of shipping a hard-coded model list.
export SOLOOM_AIGATEWAY_BASE_URL=http://127.0.0.1:8788
export SOLOOM_AIGATEWAY_API_KEY=sk-your-platform-key
soloom gateway doctor
soloom models
# No runtime YAML or runtime connect step is required for this environment-only path.
soloom provider transcribe --request ./transcribe.yaml --livesoloom gateway doctor verifies the endpoint, credential presence, and deployment-owned model
catalog without printing the key. soloom models and paid Provider commands use the same two
variables automatically. runtime connect is still available when a project needs a durable named
profile or a local Provider Host; it is not required just to use the platform Gateway.
Provider credentials never enter the program context or project YAML. A provider request creates a deferred resource handle; the Build host performs the request, records its receipt, imports the result, and exposes the resulting artifact to later authoring code.
Provider packages can also wrap a local process or an OpenAI-compatible service. See Provider packages for the package contract and examples.
CLI surfaces
| Goal | Command |
| --- | --- |
| Inspect a source video | soloom media inspect, media boundaries, reference inspect |
| Register project media | soloom assets register |
| Describe code-authored video | soloom program check or program run |
| Persist and render a program | soloom program build --live --wait |
| Discover deployed capabilities | soloom models or soloom runtime connect |
| Observe detached execution | soloom build status, build wait, history |
| Produce independent variants | soloom variants plan and soloom variants run |
| Import a HyperFrames asset | soloom assets import |
The CLI emits machine-readable YAML so an external agent can inspect facts, preserve evidence, and decide the next operation without scraping browser output.
A real editing timeline, not just a render
The browser editor is part of the creation loop. Agent-authored clips, generated media, captions, audio, and Motion Graphs appear as real timeline resources that a person can select, trim, retime, restyle, and rearrange. The timeline is the shared handoff between the agent and the editor, so a creator can take over at any point instead of starting again from a flattened MP4.
When the cut is ready, Soloom can export both delivery media and editable interchange files:
- MP4 and audio exports for publishing.
- FCPXML for Final Cut Pro and DaVinci Resolve workflows.
- FCP 7 XML for compatible legacy and interchange tools.
- Project files that preserve Soloom's own editable state.
This makes Soloom useful whether the next step is social publishing, human finishing, or a handoff to a traditional post-production suite.
Repository layout
src/shared/soloom- project model, program SDK, authoring compiler, Build and Result lifecycle.tools/- CLI, Node harness, provider host, render host, and integration checks.skills/soloom- the instructions and reference map an external agent can load.packages/andexamples/- provider packages and runnable integrations.public/- browser-rendered assets, HyperFrames runtime, and local media tooling.
Development
npm install
npm run typecheck
npm run test:run
npm run build:soloom-cli
npm run devUse npm run smoke:editor:e2e:program to exercise a normal npm program through editor preview, thumbnails, seeking, headless MP4 export, and reopening.
The repository is self-contained and does not use file dependencies from sibling workspaces. The browser editor is based on nle-video; Mediabunny provides the media inspection and export pipeline, and HyperFrames provides the Motion Graph surface.
Contributing
Issues, documentation, examples, provider packages, and code contributions are welcome. Keep new authoring surfaces open-ended: an Agent should be able to choose its own structure instead of entering a hidden fixed workflow. Before opening a pull request, run the checks that cover the area you changed and include a short reproduction or output description for user-visible behavior.
License
Soloom is released under the Apache License 2.0. See NOTICE and THIRD_PARTY_NOTICES.md for attribution and bundled dependency notices. Content and media produced through Soloom may also be subject to the terms of the providers used to create them.
