Vidkit

AI video helper CLI for text-to-speech audio generation and video frame sheet previews.

Install

Install Vidkit in a project:

pnpm add -D @viyuni/vidkit

Or run it directly:

pnpm exec vidkit --help
npx vidkit --help

Text To Speech

Generate one audio file:

pnpm exec vidkit tts "hello" -o hello.mp3

Choose a provider, model, and voice:

pnpm exec vidkit tts "hello" --provider openai --model tts-1 --voice alloy -o hello.mp3
pnpm exec vidkit tts "hello" --provider minimax --model speech-02-hd --voice male-qn-qingse -o hello.mp3

You can also use the provider/model shorthand:

pnpm exec vidkit tts "hello" --model openai/tts-1 --voice alloy -o hello.mp3
pnpm exec vidkit tts "hello" --model minimax/speech-02-hd --voice male-qn-qingse -o hello.mp3

Configuration can come from flags or environment variables:

TTS_PROVIDER=openai
TTS_MODEL=tts-1
TTS_VOICE=alloy
TTS_API_KEY=sk-...
TTS_API_BASE_URL=https://api.openai.com/v1

Load the TTS variables from an environment file with the TTS-only --env-file option. Relative paths are resolved from the current working directory, and existing environment variables take precedence over values from the file.

pnpm exec vidkit tts "hello" -o hello.mp3 --env-file .env
pnpm exec vidkit tts --json ./script.json -o ./audios --env-file ./config/tts.env

Batch TTS

Render multiple audio files from JSON:

pnpm exec vidkit tts --json ./script.json -o ./audios

Supported JSON input:

[
  "First narration line.",
  {
    "name": "intro.mp3",
    "display": "Intro",
    "tts": "Second narration line."
  }
]

String items are written as speech-001.mp3, speech-002.mp3, and so on. Object items require tts; name controls the output file name.

Frame Sheets

Vidkit uses ffmpeg to extract and stitch video frames. Make sure ffmpeg is installed and available on PATH, or pass --ffmpeg.

Generate a preview sheet:

pnpm exec vidkit sheet input.mp4 -o preview.jpg

Capture interval frames:

pnpm exec vidkit sheet input.mp4 --start 00:01:30 --every 5 --limit 12 --cols 4 --width 320 -o preview.jpg

Capture exact timestamps:

pnpm exec vidkit sheet input.mp4 --start 00:10:00 --at 0,10,20 -o preview.jpg

Use --accurate for slower but more precise seeking.

Codex Skill

This repository also ships a Codex skill for adding Vidkit workflows to other projects:

skills/vidkit

Install it with a skill installer that supports GitHub paths:

npx skills add https://github.com/viyuni/vidkit/tree/main/skills/vidkit

If your installer uses owner/repo path syntax:

npx skills add github:viyuni/vidkit/skills/vidkit

Manual fallback:

target-project/
  .codex/
    skills/
      vidkit/
        SKILL.md

Then ask Codex in the target project:

Use $vidkit to add TTS and frame-sheet workflows to this project.

Development

Install dependencies:

vp install

Run checks and tests:

vp check
vp test

Build the package:

vp pack