Skip to main content

Kairos — Find the moment that matters

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-mcp entry point for MCP clients, with global-install and direct-from-PyPI options.
  • A portable Agent Skill in skills/kairos/SKILL.md.

Version 0.3.1 fixes a face-tracking failure on fresh installations that selected OpenCV 5. Upgrade from 0.3.0 before using face-tracked portrait rendering.

Requirements

  • Python 3.10 or newer.
  • FFmpeg and ffprobe available on PATH. FFmpeg must include the ass/libass subtitle filter; check with ffmpeg -filters | grep ass.
  • uv for 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.

Check your setup (v0.4)

kairos doctor
kairos doctor --json

Doctor checks FFmpeg/ffprobe, the ASS caption filter, H.264/AAC encoders, local transcription imports, face detector data, writable output/cache/job directories, and cached model files. It never downloads model weights or validates API keys. An unwritable optional transcript cache is a warning and processing can continue without saving cache entries. A missing model is a warning: the first transcription needs internet. Required failures return exit code 1. Rendering checks the media prerequisites before transcribing.

On macOS/Homebrew, the ffmpeg-full formula includes libass. Because it is keg-only, put its bin directory before another FFmpeg installation:

brew install ffmpeg-full
export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"
kairos doctor

Apply the PATH setting in the environment that starts your agent harness and restart it. Other systems need an FFmpeg build with libass, libx264, and AAC. The setup scripts run doctor after installing Kairos and report prerequisites that still need attention.

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.

Render a short final-look preview (v0.4)

After discovering candidates, render 1–10 seconds of one chosen range with the actual crop, face tracking, export resolution, and burned captions:

kairos ./video.mp4 --candidate-plan ./candidates/review-EXAMPLE/candidates.json --select candidate_01 --preview --preview-seconds 5 --preset reels --resolution 720p --layout fit

In the review studio, choose a candidate, edit its times/settings, then click Render preview. The player switches to the rendered MP4, rather than simulating crop or captions in CSS. Back to source restores the original video. Changing settings marks the old preview as stale. The UI checks local readiness first and shows fixes for missing prerequisites.

Preview output goes into a new folder for each request and does not replace a full render or previous preview. A preview covers the first requested seconds of the selected/edited range (or the entire range if shorter). It uses the transcript cache when available and the same renderer as full exports; the final full clip still needs review for later framing/caption changes.

MCP offers check_kairos_setup and render_clip_preview. For nonblocking work, use start_clip_job(kind="preview", options={...}) with source, candidate_plan, candidate_id, and seconds plus layout/export options. Results have is_preview: true and include MP4/SRT paths.

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.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kairos-video-clipper 0.4.0
File Size Uploaded Provenance Actions
kairos_video_clipper-0.4.0.tar.gz 61.7 kB With provenance Details for kairos_video_clipper-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kairos-video-clipper 0.4.0
File Interpreter ABI Platform Actions
kairos_video_clipper-0.4.0-py3-none-any.whl Python 3 none any Details for kairos_video_clipper-0.4.0-py3-none-any.whl

Total release size: 109.9 kB

Release files / kairos_video_clipper-0.4.0.tar.gz

Download URL kairos_video_clipper-0.4.0.tar.gz
Size 61.7 kB
Tags Source
SHA-256 checksum
How to use checksums
07d24de6c196d22c0c7e2ccf24126a9c2062c3770485416580eb0866ee28036a
BLAKE2b-256 checksum
How to use checksums
f763eb62fd47d7d17c0b3b84411d6527f4888fdd25f95fa2d33e6c9e43294956
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 log

Release files / kairos_video_clipper-0.4.0-py3-none-any.whl

Download URL kairos_video_clipper-0.4.0-py3-none-any.whl
Size 48.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6db43746c97a662fde0e5d467f65554abf1f064566e7efd0fd2bdf01032900bc
BLAKE2b-256 checksum
How to use checksums
ba7c0f8b4d7bc60629718d6b0cdbfe83f62daddb4e2081389782e58237d8791a
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 log

Security for kairos-video-clipper 0.4.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.

Select from 2 files

Attestation for kairos_video_clipper-0.4.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page