Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Video & audio

video-analysis

Analyze a video with Sonilo and get back a creative brief for scoring it — a time-aligned section plan plus one or more ready-to-use generation prompts, derived from the footage itself. Use when the user has a video that needs sound but nobody knows yet what it should sound like, or when a first generation missed and you need a better prompt rather than another reroll. Generates no audio and no video; the output is text you feed into video-to-music, video-to-sfx, or video-to-sound.

sonilo-ai · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add sonilo-ai/skills --skill video-analysis

About this skill


name: video-analysis description: Analyze a video with Sonilo and get back a creative brief for scoring it — a time-aligned section plan plus one or more ready-to-use generation prompts, derived from the footage itself. Use when the user has a video that needs sound but nobody knows yet what it should sound like, or when a first generation missed and you need a better prompt rather than another reroll. Generates no audio and no video; the output is text you feed into video-to-music, video-to-sfx, or video-to-sound. license: MIT compatibility: "Requires Sonilo through either transport — the MCP server connected, or the sonilo CLI installed and signed in — plus credentials: a sonilo login sign-in, the hosted OAuth plugin, or SONILO_API_KEY. See the setup-api-key skill." allowed-tools: Bash, Read, Write, mcp__sonilo__*

Sonilo Video Analysis

Hand Sonilo a video and it returns a creative brief for scoring it: a time-aligned segments plan (what each stretch of footage wants) plus one or more variations, each a single ready-to-use generation prompt.

This skill generates nothing. No audio, no video, no file. Its whole output is text, and the text is the input to the next call.

Setup: See the setup-api-key skill to connect the Sonilo MCP server and authenticate — sonilo login (no key) or SONILO_API_KEY.

⚠️ Cost: this is a paid call, even though nothing is generated. Billing has a 10-second floor and variants_num is billed per brief, so 3 variations cost 3×. Only call it when the user has actually asked. Check get_account_services (see the account skill) if you're unsure whether free-trial runs remain.

When to reach for this

Use it when:

  • The user doesn't know what the video should sound like. "Make this sound good" is not a prompt. Analyze first, show them the variations, let them pick.
  • A first generation missed. A bad result usually means a bad brief, not a bad model. Analyzing beats rerolling: a reroll is a fresh charge on the same weak prompt.
  • The video has distinct sections and you want them scored deliberately rather than as one continuous bed. segments gives you the section boundaries the footage actually has.

Do not use it when the user already told you what they want. If they said "tense synths, drop at the 20-second mark", go straight to video-to-music — analysis would just be an extra charge between them and their track.

Transport: MCP or CLI

Pick one at the start of the session and stay on it. Do not mix the two inside a single job, and do not announce the choice.

  1. Sonilo MCP tools visible in this session (analyze_video and friends) — use them. This is the preferred path: it needs no shell, and it is the only one that survives a very long generation. If a call fails to authenticate — rather than failing on its inputs — this transport is not usable in this session: go to 2 instead of retrying it.
  2. No usable Sonilo MCP tools, but sonilo account exits 0 — use the CLI commands below. Same API, same account, same credential file. Probe with sonilo account, not sonilo whoami: whoami exits 0 even when signed out, so it cannot tell the two states apart.
  3. Neither — stop and run the setup-api-key skill. Do not call api.sonilo.com with curl to work around it; both transports handle uploads, polling and retries that a bare request does not.

One difference between the two MCP servers

analyze_video takes a local file only on the local server. The hosted (OAuth plugin) server is URL-only: it exposes video_url and nothing else. If the user's video is a local file and you are on the hosted server, use the CLI or an SDK instead of trying video_path — it is not a parameter there.

Quick Start

MCP tool call (recommended)

analyze_video(
    video_path="~/Desktop/trailer.mp4",
    prompt="focus on the chase",
    variants_num=2
)

Returns the brief inline as JSON. Nothing is saved to disk — unlike every other Sonilo tool, there is no output path, because there is no file.

On the hosted server, pass video_url instead of video_path.

Python (pip install sonilo)

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

brief = client.video_analysis.analyze(
    video="trailer.mp4",
    prompt="focus on the chase",
    variants_num=2,
)

for segment in brief.segments:
    print(f"{segment.start}-{segment.end}s [{segment.label}] {segment.prompt}")

# Feed a variation's prompt straight into a generation call.
score = client.video_to_music.generate(
    video="trailer.mp4", prompt=brief.variations[0].prompt
)
score.save("score.m4a")

The method is analyze(), not generate(), and the result has no save() — there is nothing to download.

JavaScript / TypeScript (npm install sonilo)

import { SoniloClient } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const brief = await client.videoAnalysis.analyze({
  video: "./trailer.mp4",
  prompt: "focus on the chase",
  variantsNum: 2,
});

const score = await client.videoToMusic.generate({
  video: "./trailer.mp4",
  prompt: brief.variations![0]!.prompt,
});

segments and variations are both optional on the type — a processing or failed poll carries neither — so guard with ?? [] rather than asserting.

CLI (npm install -g sonilo-cli or pip install sonilo-cli)

sonilo video-analysis --video trailer.mp4 --prompt "focus on the chase" --variants 2

The brief goes to stdout as JSON, so it pipes:

sonilo video-analysis --video trailer.mp4 --output brief.json
sonilo video-to-music --video trailer.mp4 --prompt "$(jq -r '.variations[0].prompt' brief.json)"

--output is the only way this command writes a file, and it writes the brief, not media.

cURL (raw REST API, no MCP host)

curl -X POST "https://api.sonilo.com
Read the complete source ↗