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
pnpm exec vidkit tts "你好" --provider xiaomi --model mimo-v2.5-tts --voice 冰糖 -o hello.wav

Xiaomi MiMo TTS supports natural-language speech instructions. The target speech text is sent as the assistant message and --instructions is sent as the optional user message:

pnpm exec vidkit tts "老板，我跟你说个好消息！" \
  --provider xiaomi \
  --model mimo-v2.5-tts \
  --voice 冰糖 \
  --instructions "非常开心，语速稍快，带一点得意" \
  -o hello.wav

instructions is a common TTS option. Providers that support it can consume the same value; Xiaomi maps it to the optional user message required by the MiMo speech-synthesis protocol.

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=xiaomi
TTS_MODEL=mimo-v2.5-tts
TTS_VOICE=冰糖
TTS_INSTRUCTIONS=自然、清晰的旁白
TTS_API_KEY=...
TTS_API_BASE_URL=https://api.xiaomimimo.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.wav",
    "display": "Intro",
    "tts": "Second narration line.",
    "instructions": "Warm, calm narration with a slightly slower pace."
  }
]

Object items require tts; name controls the output file name. An object's instructions overrides the global --instructions / TTS_INSTRUCTIONS value for that item. Items without instructions inherit the global value. Auto-generated names keep the existing .mp3 default for OpenAI/MiniMax and use .wav for Xiaomi MiMo.

For example, use one default style with per-line overrides:

pnpm exec vidkit tts --json ./script.json \
  --provider xiaomi \
  --model mimo-v2.5-tts \
  --voice 冰糖 \
  --instructions "自然、清晰的女性旁白" \
  -o ./audios

[
  {
    "name": "intro.wav",
    "tts": "欢迎来到今天的视频。"
  },
  {
    "name": "surprised.wav",
    "tts": "等等！你刚才说什么？",
    "instructions": "突然惊讶，提高音量，语速稍快"
  }
]

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