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.

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.

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

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

Pushing a version tag such as v0.2.3 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.

The first automatic publication is version 0.2.3. A pending PyPI Trusted Publisher must be configured with owner gempurbayu, repository kairos, workflow publish.yml, and environment pypi. The release tag must match the package version exactly.

License

No license file has been added yet. Until a license is selected, this repository does not grant permission to reuse or redistribute its code.

Metadata

Release files for kairos-video-clipper 0.2.3

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.2.3
File Size Uploaded Provenance Actions
kairos_video_clipper-0.2.3.tar.gz 12.4 kB With provenance Details for kairos_video_clipper-0.2.3.tar.gz

Built distribution (wheel)

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

Total release size: 25.8 kB

Release files / kairos_video_clipper-0.2.3.tar.gz

Download URL kairos_video_clipper-0.2.3.tar.gz
Size 12.4 kB
Tags Source
SHA-256 checksum
How to use checksums
9d4552c1e782bf6acb76fdc87faba57d4080b4b5a2501a712ced5b3528de5c24
BLAKE2b-256 checksum
How to use checksums
00af2707783c51568ff0c928e249df0c9d0fa14d1c3e627b9eccf566a74812cd
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.2.3-py3-none-any.whl

Download URL kairos_video_clipper-0.2.3-py3-none-any.whl
Size 13.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5b9ce799b1e2b209d34f5f43296f0dd1d7c57470b029616329f6cf758c838486
BLAKE2b-256 checksum
How to use checksums
7fa720f66573a978af2e948c0cf1d8695b24129bb43cdb5ea166516d7042c6bc
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.2.3

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