Kairos
Find the moment that matters. Kairos is a local-first tool that turns authorized long-form videos into portrait short clips. It transcribes speech, finds candidate highlights, tracks the largest visible face while reframing, and renders captioned MP4 clips with editable subtitle files.
Kairos can run from the command line or expose the same workflow as an MCP server for Codex, Hermes, OpenClaw, and other compatible agent harnesses.
Features
- Local speech transcription with faster-whisper and word-level timestamps.
- Offline highlight scoring, with optional Gemini-assisted selection.
- Portrait 9:16 rendering with FFmpeg and optional OpenCV face tracking.
- TikTok-style karaoke captions burned into each MP4, plus an editable SRT file.
- A JSON manifest containing selected timestamps, titles, scores, and output paths.
- One shared
kairos-mcpentry point for MCP clients, with global-install and direct-from-PyPI options. - A portable Agent Skill in
skills/kairos/SKILL.md.
Requirements
- Python 3.10 or newer.
- FFmpeg and ffprobe available on
PATH. FFmpeg must include theass/libass subtitle filter; check withffmpeg -filters | grep ass. uvfor the global MCP installation instructions below.- Internet access to install dependencies and download Whisper model weights on first use. Gemini requests and authorized YouTube downloads also require internet access.
- Enough disk space and memory for the selected Whisper model and video rendering.
Install
git clone https://github.com/gempurbayu/kairos.git
cd kairos
python -m venv .venv
Activate the virtual environment, then install Kairos:
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .
The kairos command is now available in the active virtual environment. For Gemini-assisted highlight selection, copy .env.example to .env and set GEMINI_API_KEY. Without a key, Kairos uses its offline transcript heuristic. Keep .env private; it is excluded by .gitignore.
Quick start
Process a local video without using Gemini:
kairos ./path/to/video.mp4 --offline --count 3 --output ./output
Use Gemini-assisted selection when GEMINI_API_KEY is configured:
kairos ./path/to/video.mp4 --count 5 --min-duration 20 --max-duration 45
YouTube downloads require both the explicit --allow-download flag and permission to use the video:
kairos 'https://www.youtube.com/watch?v=VIDEO_ID' --allow-download --count 3
The first transcription run downloads the selected faster-whisper model. base is the default and is a practical starting point for CPU use.
CLI options
| Option | Default | Description |
|---|---|---|
--output PATH |
output |
Directory for clips, subtitles, and manifest. |
--count N |
3 |
Maximum number of clips to create. |
--min-duration SECONDS |
20 |
Minimum clip duration. |
--max-duration SECONDS |
60 |
Maximum clip duration. |
--model NAME |
base |
faster-whisper model to use, such as base or small. |
--offline |
off | Do not use Gemini highlight selection. |
--no-face-tracking |
off | Use a centered crop instead of face tracking. |
--preset NAME |
unset | TikTok, Reels, or Shorts vertical export target. |
--resolution NAME |
auto |
auto (1080p), 720p, or 1080p. |
--layout NAME |
portrait | Face-tracked portrait, full-frame fit, or custom landscape. |
--allow-download |
off | Explicitly permit a YouTube download when you have the rights to use that video. |
Run kairos --help to see the full command help.
Connect an agent harness
Install FFmpeg and uv, then install Kairos as an editable global uv tool:
# macOS/Linux
./scripts/setup.sh
# Windows PowerShell
.\scripts\setup.ps1
Every MCP-compatible harness can then launch the same command, kairos-mcp; no per-harness virtual-environment path is needed. Register the server once in each harness using the examples in docs/INTEGRATIONS.md. The existing youtube-clipper and youtube-clipper-mcp command names remain available as compatibility aliases.
To skip the global installation, configure the harness to launch Kairos from PyPI with uvx. For example, in Codex CLI:
codex mcp add kairos -- \
uvx --from kairos-video-clipper kairos-mcp
The Codex desktop config, Hermes, and OpenClaw examples are in docs/INTEGRATIONS.md. The first uvx launch downloads and prepares dependencies; later launches use uv's cache. Install FFmpeg on the machine running Kairos. Direct uvx installs use offline highlight selection unless GEMINI_API_KEY is available in the server process environment. These PyPI commands work after version 0.2.3 finishes publishing.
The MCP server provides these tools:
| Tool | Purpose |
|---|---|
transcribe_local_video |
Transcribe a local video and return timestamped segments. |
find_highlights |
Find and rank candidate moments in a local video. |
generate_clips |
Render portrait clips, captions, SRT files, and a manifest. |
YouTube downloads remain disabled unless a caller explicitly sets allow_download: true. Confirm that the user has the rights to use the source video before enabling downloads.
Example request in an agent chat
After connecting Kairos, ask the agent:
Create three portrait clips from
/absolute/path/to/podcast.mp4. Make each 20–45 seconds, use offline highlight selection and face tracking, and save the MP4s, SRT files, and manifest to/absolute/path/to/kairos-output. Summarize the selected timestamps when finished.
This calls generate_clips with arguments like:
{
"source": "/absolute/path/to/podcast.mp4",
"output_dir": "/absolute/path/to/kairos-output",
"count": 3,
"min_duration": 20,
"max_duration": 45,
"use_ai": false,
"face_tracking": true
}
Install the Agent Skill
Install the portable skill into a supported agent with the Vercel Skills CLI:
npx skills add gempurbayu/kairos --skill kairos -g
The skill provides agent instructions; the MCP installation provides the executable tools.
Install from PyPI
Install Kairos from PyPI:
uv tool install kairos-video-clipper
For a direct harness launch without a Git URL, configure the MCP command as uvx with arguments --from, kairos-video-clipper, and kairos-mcp. The first launch downloads the package and dependencies; subsequent launches use uv's cache.
Preview and select candidates (v0.3)
Requires Kairos 0.3 or newer. Upgrade with uv tool upgrade kairos-video-clipper, or install this checkout with pip install -e ..
kairos ./video.mp4 --discover --mode instruction --goal "useful tips" --offline --count 5 --output ./candidates
kairos ./game.mp4 --discover --mode gaming --goal "clutch funny reactions" --offline --output ./candidates
Discovery writes a new review folder containing candidates.json and up to three JPEG thumbnails per candidate. Review the returned plan_path, IDs, transcript excerpts, and reasons, then render only your chosen IDs:
kairos ./video.mp4 --candidate-plan ./candidates/review-EXAMPLE/candidates.json --select candidate_01 candidate_03 --output ./output/reviewed
Replace review-EXAMPLE with the actual review folder. A SHA-256 fingerprint checks that the plan targets the same video. Rendering reuses the transcript cache when the video bytes, model, engine version, and transcription settings match.
Modes are auto, conversation, instruction, and experimental gaming. Auto mode classifies each candidate window from transcript cues, with unknown when evidence is insufficient. Explicit modes are retained but a mismatch warning is shown when detected content differs. Offline goal matching maps a small set of common English/Indonesian editorial concepts (such as funny/lucu and reaction/reaksi), with literal matching for other terms; it is not general multilingual semantic understanding. Use --goal with both discovery and direct rendering. Optional Gemini selection also receives the mode and cross-language goal, then its proposed ranges are aligned back to transcript windows.
Candidate scores include hook, context, pacing, goal relevance, repetition/CTA and topic-transition penalties, audio dynamics, and sampled frame changes. Windows are grouped using ASR punctuation and speech pauses. Dependent openings, unanswered questions, or uncertain endings are flagged, rather than guaranteed to be complete. The review page shows detected content, matched goal concepts, and boundary warnings.
Confidence labels are heuristic, not calibrated probabilities. Audio/frame signals are sampled only for the transcript shortlist, so silent action footage is not supported. Gaming does not recognize specific events or HUD information. Use --no-media-analysis to skip audio/frame sampling.
For MCP, call discover_clip_candidates, review the response, and pass plan_path as candidate_plan plus the chosen candidate_ids to generate_clips. Existing find_highlights and direct rendering remain available.
Local review studio (v0.3)
Open a candidate plan in your browser:
kairos ./video.mp4 --review --candidate-plan ./candidates/review-EXAMPLE/candidates.json
Kairos starts a loopback-only server and opens a session URL. The page lets you play candidate ranges, select clips, edit start/end seconds, choose a layout, and start/cancel a render job. Completed jobs offer MP4 and SRT links. Keep the terminal running; Ctrl+C closes the review server. Revisions are saved separately so the original candidate plan stays unchanged. Edited timestamps are validated against the source duration; original transcript excerpts and scores are not recalculated after edits.
Layouts: portrait follows the largest face when enabled, fit keeps the full source frame inside a padded 9:16 canvas, and landscape fits the source into 16:9. Gaming and instruction review sessions default to fit. The player previews the original source; final layout, tracking, and captions are applied during render. Browser playback depends on the source codec; use an H.264/AAC MP4 if your browser cannot play the input. The same presets are available through CLI --layout and MCP generate_clips(layout=...) or render-job options.
For an authorized YouTube source, discovery can retain the downloaded video beside its plan:
kairos 'https://www.youtube.com/watch?v=VIDEO_ID' --discover --allow-download --mode gaming --offline --output ./candidates
Use the returned local source and plan_path to open the review studio. Downloading remains opt-in and requires authorization to process the source.
Platform presets and output resolution (v0.3)
Choose a platform and let Kairos select the vertical export dimensions:
kairos ./video.mp4 --preset tiktok --offline
kairos ./video.mp4 --preset reels --resolution 720p --layout fit --offline
kairos ./video.mp4 --preset shorts --resolution 1080p --offline
| Target | Auto / 1080p | 720p | Aspect ratio |
|---|---|---|---|
| TikTok, Reels, Shorts | 1080 × 1920 | 720 × 1280 | 9:16 |
| Custom landscape | 1920 × 1080 | 1280 × 720 | 16:9 |
The platform presets are convenient vertical export targets. They currently share the same dimensions and do not claim to validate every platform upload requirement. auto means 1080p; it does not detect a platform from the input URL. Choose fit to keep all source content with padding, or portrait to crop/follow faces. Platform presets cannot be combined with landscape; omit --preset for a custom landscape export. A lower-resolution source can be upscaled but does not gain original detail.
The review studio includes platform/resolution dropdowns and a live dimensions summary. Set initial choices with --review --preset reels --resolution 720p. MCP render tools and job options accept the same preset and resolution names. The output manifest records requested/resolved resolution, dimensions, aspect ratio, layout, and codecs. MP4 video uses H.264/yuv420p and audio uses AAC.
Background jobs and transcript cache (v0.3)
For long-running MCP work, start a job instead of holding one tool call open:
{
"kind": "discover",
"options": {
"source": "/absolute/path/to/video.mp4",
"count": 5,
"mode": "instruction",
"goal": "useful tips",
"use_ai": false
}
}
Call start_clip_job with that object, then get_clip_job with the returned job_id. Status reports queued, running, completed, failed, or cancelled, an estimated phase progress from 0 to 100, and the completed result. Use include_result: false for lightweight status checks. After review, start a render job with source, candidate_plan, and candidate_ids inside options. Job options use Python pipeline parameter names (source, not path).
Each job has its own output folder. One job runs at a time, with at most eight active/queued jobs per server session. cancel_clip_job requests cancellation; poll until terminal status. FFmpeg subprocesses are terminated and reaped. Whisper model loading/inference and network calls may finish their current operation before cancellation is observed. Partial output can remain in the job folder and is not a completed result.
Jobs belong to the running MCP server session; restart recovery and resume are not supported. Status snapshots and results are written under ~/.cache/kairos/jobs (override with KAIROS_JOBS_DIR). Old job files are not automatically removed.
Transcripts are cached locally under ~/.cache/kairos/transcripts. Set KAIROS_CACHE_DIR to choose another cache root or KAIROS_DISABLE_CACHE=1 to bypass caching. Cache files contain speech text and timestamps; keep them private and delete the directory to clear them. Cache corruption or an unwritable cache falls back to transcription. Different video bytes or models create separate entries. No models, transcript cache files, or user media are committed to this repository.
See docs/EVALUATION.md for the synthetic integration checks and the procedure for evaluating candidate quality on authorized real videos.
Configuration
| Variable | Default | Purpose |
|---|---|---|
GEMINI_API_KEY |
unset | Enables Gemini-assisted highlight selection. Without it, offline scoring is used. |
GEMINI_MODEL |
gemini-2.5-flash |
Gemini model for highlight selection. |
WHISPER_MODEL |
base |
Default local transcription model; --model overrides it for a CLI run. |
Variables can be placed in a local .env file or supplied by the process environment. Never commit real credentials.
Output files
Each run writes files into the selected output directory:
output/
├── clip_01.mp4
├── clip_01.srt
├── clip_02.mp4
├── clip_02.srt
└── manifest.json
Captions are burned into the MP4 in short word groups with karaoke highlighting. SRT files remain editable in video-editing software. The manifest records clip timestamps, titles, scores, selection method, face-tracking setting, and output paths. Existing files with the same names are overwritten, so choose a different output directory to retain previous results.
How it works and known limitations
- faster-whisper transcribes audio locally and supplies word timestamps.
- Offline selection scores transcript windows using speech pacing, vocabulary variety, hook words, and sentence completion. Gemini can rank candidate moments when configured; failures fall back to offline selection.
- Face tracking samples frames and follows the largest detected face. If no face is found, Kairos uses a centered crop. It does not identify or follow a particular person.
- Highlight selection is based on transcript signals; it is not visual scene understanding and cannot guarantee virality or editorial quality. Content labels and boundary evidence are heuristic. Common English/Indonesian concept matching does not translate arbitrary goals or identify gameplay events.
- Videos with little or no speech may produce fewer clips or no clips.
- Kairos does not bypass DRM, access restrictions, or platform safeguards. Follow applicable copyright rules and platform terms when processing or downloading videos.
Development
python -m pip install -e . pytest
python -m pytest -q
GitHub Actions runs the test suite on Python 3.10, 3.11, and 3.12 for pushes and pull requests. Before changing behavior, review AGENTS.md for repository conventions and safety requirements. Keep user media, generated outputs, API keys, and local .env files out of commits.
Release and PyPI publishing
See CHANGELOG.md for release history. Pushing a version tag such as v0.3.0 runs tests, builds the distributions, checks that the tag matches pyproject.toml, and publishes them to PyPI through GitHub Actions. The publisher uses PyPI Trusted Publishing (OIDC), so no PyPI API token is stored in GitHub.
Version 0.2.3 was the first automatic publication. The PyPI Trusted Publisher is configured for owner gempurbayu, repository kairos, workflow publish.yml, and environment pypi. Every release tag must match the package version exactly.
License
Kairos is licensed under the MIT License. Copyright (c) 2026 Gempur Bayu. Third-party dependencies, models, and source videos remain subject to their own licenses and terms.
Metadata
Release files for kairos-video-clipper 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kairos_video_clipper-0.3.0.tar.gz | 52.6 kB | With provenance | Details for kairos_video_clipper-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kairos_video_clipper-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for kairos_video_clipper-0.3.0-py3-none-any.whl |
Total release size: 94.7 kB
Release files / kairos_video_clipper-0.3.0.tar.gz
| Download URL | kairos_video_clipper-0.3.0.tar.gz |
|---|---|
| Size | 52.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c004f0907db863e853861021d988da3981e79075688abd541dfb219d885f23f
|
|
BLAKE2b-256 checksum How to use checksums |
c60e3cc6d1cc6256ca710dfb0edd45be875db5b15486d3d615dbe0196f277195
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / kairos_video_clipper-0.3.0-py3-none-any.whl
| Download URL | kairos_video_clipper-0.3.0-py3-none-any.whl |
|---|---|
| Size | 42.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
14a977faf8e5d8eef05cdc18fe5c6c24c2eefa193e57098a2da29271efe6b7f5
|
|
BLAKE2b-256 checksum How to use checksums |
28486d82a9cf6b720d6744e1917cf8f70d001dbbae62293f1647426c28343772
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for kairos-video-clipper 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kairos_video_clipper-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.