For developers

Clips Kitty SDK

Teach Clips Kitty your game. Write a small Python plugin that finds, understands or rates the moments in a video. Clips Kitty does the rest.

Your plugin knows what a great moment looks like in your game. Clips Kitty downloads the video, writes down what is said, and turns the moments into finished vertical clips with captions and titles, on the creator's own PC.

No Clips Kitty release runs plugins yet. Plugins made with SDK 1.2.0 need the first release that includes it; until that is out, run Clips Kitty from source.

Start building

How a plugin fits in

A plugin is a folder with a manifest, clipskitty.yaml, and a Python script. Clips Kitty starts it for each video with a job folder, and every step is optional: a video that uses no plugin is made exactly as before.

Clips Kitty SDK

Inputa link or a video file
VideoClips Kitty downloads it and writes down what is said
Your pluginevery step is optional
- findpicks the momentsbuilt
- understandsays what happens in each onebuilt
- ratescores each momentbuilt
- editsuggests edits for the creatorbuilt
Clips Kittydoes every step no plugin does, then cuts, frames and captions the clips
Creator / Social Platformposts when the creator clicks Publish, or on a schedule or automatic posting the creator switched on

One plugin can find moments for a video; it replaces Clips Kitty's own finding.
Up to 3 plugins can understand and up to 3 can rate, after any finder.
Up to 3 plugins can suggest edits for the clips that will be made.
A plugin's role comes from inputs and outputs in its manifest (Steps).
Edit plugins suggest edits that wait for the creator in the editor (Steps).
Posting isn't a plugin step: Clips Kitty posts clips itself, and through WoopSocial it can post to many sites at once on the creator's own account. kind: publisher is refused: plugins don't post.

Affiliate link - Clips Kitty may earn a commission if you sign up through it, at no extra cost to you.

What you can build

Someone who knows one game can tell a great moment from a loud one far better than a general-purpose detector. Three kinds of plugin, each with a template to start from:

Game events

Your game shows something when a big play happens: a banner, a line in the kill feed, an icon, a sound. A finder looks for it and hands Clips Kitty the moments. Template: game-events, or transcript to find the words the commentary says.

A rater for your community's taste

Clips Kitty or another plugin finds the moments; your rater gives each one a new score, by what your viewers like and what they skip. Template: rater.

Notes for better titles

Say what happens in each moment, and Clips Kitty's AI uses it when it writes the clip's title, description and hashtags. Template: understander.

Wanted: game events for genres the big clipping apps barely cover, such as fighting games, racing, strategy, card games, MMOs, and retro or emulated games. The Wanted list in Awesome Clips Kitty has more ideas nobody has built yet (it is kept in sections.yaml).

Quickstart

Three commands: install the SDK, make a plugin from the game-events template, and run it on a test video the SDK makes. The template is for Quarkbloom Arena, a made-up game; put your own GitHub name, in lower case, in place of your-github-name.

PowerShell (Windows)

py -m pip install "clipskitty-sdk[yaml,test] @ git+https://github.com/ColinGPT9/clips-studio#subdirectory=sdk/python"
py -m clipskitty_sdk new quarkbloom-bursts --template game-events --publisher your-github-name
py -m clipskitty_sdk run quarkbloom-bursts --sample

bash (macOS, Linux)

python -m pip install "clipskitty-sdk[yaml,test] @ git+https://github.com/ColinGPT9/clips-studio#subdirectory=sdk/python"
python -m clipskitty_sdk new quarkbloom-bursts --template game-events --publisher your-github-name
python -m clipskitty_sdk run quarkbloom-bursts --sample

The last command makes a 40-second test video with a red banner and a loud sound, runs the plugin on it the way Clips Kitty would, and prints the one moment it finds. You need Python 3.11, the Python Clips Kitty runs plugins on; FFmpeg on PATH, for the test video; and Git, because the SDK installs from GitHub. If you use a virtual environment, make it beside your plugin's folder, never inside it.

No Clips Kitty release runs plugins yet. Plugins made with SDK 1.2.0 need the first release that includes it; until that is out, run Clips Kitty from source.

Your first game pipeline The SDK on GitHub

Building blocks

Modules for the work most game plugins share, in SDK 1.2.0. Each says what it needs, and your plugin's manifest asks for it.

`media`

Reads the video with the FFmpeg Clips Kitty hands over: its size, a part of the screen frame by frame, one frame as a JPEG, its loudness and its scene cuts.

Needs: FFmpeg (the ffmpeg permission), and video.read for the video itself.

`signals`

Turns numbers and frames into moments: how much of a frame is one colour, how bright it is, loud spikes, stretches of time, and a moment fitted to the clip lengths the creator chose.

Needs nothing of its own: it works on the numbers and frames that media gives it.

`text`

Finds words in what is said: whole words in any case, with the times they are said, and which ones fall inside a moment.

Needs: the transcript (transcript in inputs and the transcript.read permission).

`local_model`

Asks the creator's local model in Clips Kitty a question, about a frame too when the model can see pictures.

Needs: the ollama permission, and a creator who uses a local model in Clips Kitty. It uses that model only on this PC: it refuses when Clips Kitty's AI runs at a cloud provider or at an address off this PC, and it ignores proxy settings, so the frames never leave the PC.

`testing`

Runs your plugin from its own tests, the way Clips Kitty would, on the SDK's test video or test transcript.

For tests on your PC, not in the app: install the test extra for pytest.

Signals cookbook Every call in the SDK

Free and yours

The SDK is MIT (licence). Using it doesn't put your plugin under the AGPL, so your plugin can have any licence; code that new copied from a template keeps the SDK's MIT notice, in TEMPLATE-LICENSE.txt. Clips Kitty itself is AGPL-3.0-or-later.
Your plugin keeps its own licence, open or closed, and the Marketplace shows it. Your code stays in your own repository.
No fee and no share. Listing, updating and installing cost nothing, and Clips Kitty takes no share of what you earn. Link your own pricing, sponsors or support page from your manifest.

What creators see

Installing runs nothing: a plugin's code first runs when a video uses it. Before anything is installed, Clips Kitty's install screen starts with "This pipeline is a program from the internet. It can do anything you can do on this PC." Then it shows the publisher, the source and commit, the licence, the labels, each permission with whether Clips Kitty enforces it or only the developer says so, and a ⚠ line for each kind of data that leaves the PC. An update lists what it adds.

Label	What it means
Community · not reviewed by a person	Installed from a listing in Awesome Clips Kitty whose automated checks passed.
✓ Official · made by the Clips Kitty project	From a repository that belongs to the Clips Kitty project.
✓ Compatible	One version installed and ran on a sample video. An automated check, not a review.
Unofficial · not made or endorsed by the makers of …	A listing that names a game, built from the games it names.

Every plugin runs on the creator's PC with their rights, like any program; Clips Kitty doesn't sandbox it. The install screen says what it declares. What Clips Kitty does and doesn't protect.

Get listed

Creators find plugins in Clips Kitty's Marketplace, which reads Awesome Clips Kitty, a catalog kept on GitHub. Getting in costs nothing.

Commit your plugin to a public GitHub repository and push it.
From the folder that holds your plugin's folder, write its listing file with listing. It checks that everything is committed and pushed and that your GitHub name owns the repository.
Open one pull request to ColinGPT9/awesome-clips-kitty with that one file. Its check says why if the listing is refused, and the catalog's index is rebuilt after the merge.
Once it is merged, it reaches creators through Clips Kitty's online list. In the versions of Clips Kitty that have the Marketplace, it shows up the next time the Marketplace checks that list (when it opens, at most once a day), or at once with Check for new pipelines.

PowerShell (Windows)

py -m clipskitty_sdk listing quarkbloom-bursts --section gaming/generic

bash (macOS, Linux)

python -m clipskitty_sdk listing quarkbloom-bursts --section gaming/generic

A listing is for your real plugin: listing refuses one that still has the template's placeholders. Getting listed has the rest.

Help

Ask in GitHub Discussions, and report a problem with the SDK or its docs in Issues. The troubleshooting page lists the messages you may meet, and what to do about each.

Discussions Issues Troubleshooting

Questions

Can I name a real game?

Yes, as an unofficial plugin. A listing that names games shows "Unofficial · not made or endorsed by the makers of" those games in the Marketplace. Our own examples use Quarkbloom Arena, a made-up game.

Is a plugin sandboxed?

No. Every plugin runs on the creator's PC with their rights, like any program; Clips Kitty doesn't sandbox it. The install screen says what it declares, and which of those Clips Kitty enforces.

Which Python do plugins run on?

Clips Kitty's own: Python 3.11, with the standard library (except a few modules it leaves out, which validate warns about) and the SDK. Clips Kitty can't install other packages yet. Test on 3.11: newer Python syntax or library calls fail there.

Which Clips Kitty runs plugins?

No Clips Kitty release runs plugins yet. Plugins made with SDK 1.2.0 need the first release that includes it; until that is out, run Clips Kitty from source. The README says how: From source.

What about edit and posting?

Edit is built, and posting isn't a plugin step. Edit plugins suggest edits that wait for the creator in the editor: cuts, mutes, the volume, fades, the speed, a hook title or a layout. Clips Kitty doesn’t put a suggestion into a clip until you use it in the editor and apply your edits (Apply edits, or Apply edits & upload). Clips Kitty posts clips itself, and through WoopSocial it can post to many sites at once on the creator's own account. A manifest that asks for a publisher (kind: publisher) is refused: plugins don't post.

Does a rater decide what an automatic channel posts?

Yes, where it posts only the best few clips. When a watched channel or the daily schedule posts only the best few, the scores decide which ones go out, so a rating plugin decides that; elsewhere it decides the order. A moment a rater scores under the creator's minimum score is set aside, unless the creator marked it a must-have.