takumi-cli 1.2.0 → 1.2.3

package/README.md

@@ -1,150 +1,159 @@
 # takumi (匠)
 
-The craftsman's toolkit for shaping video assets.
+A command-line toolkit for processing video assets. Convert, trim, caption, thumbnail, and inspect videos — one command at a time or in batch across folders.
+
+Works on macOS, Windows, and Linux.
 
 ## Install
 
-### macOS (Homebrew)
+### macOS
 
 ```bash
 brew tap kaiyiwong/tap
 brew install takumi
+takumi setup
 ```
 
-### Any platform (npm)
+`setup` installs ffmpeg and whisper via Homebrew.
 
-Requires [Node.js](https://nodejs.org) and [Git](https://git-scm.com) (Git provides bash on Windows).
+### Windows
 
-```bash
-npm install -g takumi-cli
-```
+**Prerequisites:**
 
-### Then install dependencies
+1. Install [Node.js](https://nodejs.org) (LTS recommended)
+2. Install [Git for Windows](https://git-scm.com/download/win)
 
-```bash
+Then open PowerShell:
+
+```powershell
+npm install -g takumi-cli
 takumi setup
 ```
 
-This installs ffmpeg and whisper. On macOS it uses Homebrew, on Linux it uses your system package manager, and on Windows it uses winget, chocolatey, or scoop.
+`setup` installs ffmpeg via winget, chocolatey, or scoop (whichever is available).
 
-### MCP Server (Claude Code, Kiro, etc.)
-
-takumi includes an MCP server so AI clients can use all commands as tools.
+### Linux
 
 ```bash
-takumi mcp-config
+npm install -g takumi-cli
+takumi setup
 ```
 
-This prints the JSON config block. Paste it into your MCP settings file:
+`setup` installs ffmpeg and whisper via apt, dnf, or pacman.
 
-- **Claude Code:** `~/.claude.json` or project `.mcp.json`
-- **Kiro:** `.kiro/settings/mcp.json`
+## Commands
 
-Then just talk naturally — "convert these for FireTV", "generate Japanese captions for this folder".
+| Command | Description |
+|---------|-------------|
+| `takumi convert <path> [crf] [max_height]` | Convert to FireTV-optimized H.264 MP4 |
+| `takumi trim <video> <start> <end>` | Cut a clip between timestamps |
+| `takumi cc <path> [lang] [model] [format]` | Generate captions using Whisper |
+| `takumi thumb <path> [timestamp]` | Extract a poster image (JPG) |
+| `takumi info <path>` | Show video metadata |
+| `takumi gif <video> <start> <end> [width]` | Create animated GIF from a clip |
+| `takumi strip <path> <audio\|video\|both>` | Extract audio/video as separate tracks |
+| `takumi srt2vtt <path>` | Convert SRT subtitles to VTT |
+| `takumi vtt2srt <path>` | Convert VTT subtitles to SRT |
 
-## Commands
+All commands accept a single file or a folder (processes all videos recursively). Existing outputs are skipped on re-run so it's safe to retry.
 
-### Generate Captions
+### Examples
 
 ```bash
-takumi cc video.mp4              # auto-detect language
-takumi cc ./videos ja            # Japanese, all videos in folder
-takumi cc ./videos en large vtt  # English, large model, VTT format
-```
+# Convert all videos in a folder for FireTV
+takumi convert ./videos
 
-Options: `[language]` `[model: tiny|base|small|medium|large]` `[format: srt|vtt]`
+# Higher quality conversion, max 720p
+takumi convert ./videos 21 720
 
-### Convert to FireTV MP4
+# Trim a 75-second clip
+takumi trim video.mp4 00:01:30 00:02:45
 
-```bash
-takumi convert video.mp4         # single file
-takumi convert ./videos          # batch folder
-takumi convert ./videos 21       # higher quality (CRF 21)
-takumi convert ./videos 23 720   # max 720p
-```
+# Generate Japanese captions with the large model
+takumi cc ./videos ja large
 
-Outputs H.264 High Profile MP4 with mod16 dimensions, AAC audio, faststart flag. Auto-detects 16:9 vs 4:3 aspect ratio.
+# Thumbnail at a specific frame
+takumi thumb video.mp4 00:00:15
 
-Options: `[crf: 18-28, default 23]` `[max_height: default 1080]`
+# Create a GIF from a 5-second clip
+takumi gif video.mp4 00:00:05 00:00:10
 
-### Trim Clip
+# Extract audio only
+takumi strip video.mp4 audio
 
-```bash
-takumi trim video.mp4 00:01:30 00:02:45
+# Check resolution, codec, duration
+takumi info ./videos
 ```
 
-Cuts a segment between two timestamps. Uses stream copy (no re-encoding) so it's fast.
+## AI Integration (MCP)
 
-### Extract Thumbnail
+takumi includes an MCP server so AI clients like Claude Code and Kiro can use all commands as tools. No syntax to remember, just describe what you want.
 
 ```bash
-takumi thumb video.mp4           # frame at 00:00:01
-takumi thumb video.mp4 00:00:15  # frame at specific time
-takumi thumb ./videos            # all videos in folder
+takumi mcp-config
 ```
 
-Extracts a high-quality JPG poster image at the video's native resolution.
+This prints the JSON config block for each client. Paste the relevant one into:
 
-Options: `[timestamp: default 00:00:01]`
+- **VS Code:** `.vscode/mcp.json` (uses `"servers"`)
+- **Claude Code:** `~/.claude.json` or project `.mcp.json` (uses `"mcpServers"`)
+- **Kiro:** `.kiro/settings/mcp.json` (uses `"mcpServers"`)
 
-### Video Info
+Once configured, just ask in natural language:
 
-```bash
-takumi info video.mp4            # single file
-takumi info ./videos             # all videos in folder
-```
+- "convert all the videos in ~/projects/campaign for FireTV"
+- "what's the resolution and duration of this video?"
+- "generate Japanese captions for the videos in this folder"
+- "trim the intro, keep only 00:01:30 to 00:04:00"
+- "extract the audio from meeting.mp4"
+- "make a gif from the first 5 seconds of demo.mp4"
 
-Shows duration, resolution, codecs, bitrate, and file size.
-
-### Create GIF
+## Update
 
 ```bash
-takumi gif video.mp4 00:00:05 00:00:10       # 480px wide (default)
-takumi gif video.mp4 00:00:05 00:00:10 320   # 320px wide
+# Homebrew (macOS)
+brew update && brew upgrade takumi
+
+# npm (any platform)
+npm update -g takumi-cli
 ```
 
-Creates an optimized animated GIF from a clip. Uses palette generation for better colors.
+## Troubleshooting
 
-Options: `[width: default 480]`
+### Windows: `takumi` is not recognized
 
-### Strip Audio/Video
+The npm global bin directory may not be in your PATH. Run this in PowerShell:
 
-```bash
-takumi strip video.mp4 audio     # extract audio only (.m4a)
-takumi strip video.mp4 video     # extract video only, no audio
-takumi strip video.mp4 both      # extract both as separate files
-takumi strip ./videos both       # batch folder
+```powershell
+npm prefix -g
 ```
 
-Uses stream copy (no re-encoding).
-
-### Convert SRT to VTT
+If the output (e.g. `C:\Users\<you>\AppData\Roaming\npm`) is not in your PATH, add it:
 
-```bash
-takumi srt2vtt subtitle.srt      # single file
-takumi srt2vtt ./videos          # all SRTs in folder
+```powershell
+[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Users\$env:USERNAME\AppData\Roaming\npm", "User")
 ```
 
-### Convert VTT to SRT
+Then close and reopen PowerShell.
 
-```bash
-takumi vtt2srt subtitle.vtt      # single file
-takumi vtt2srt ./videos          # all VTTs in folder
-```
+### Windows: bash not found
 
-## Notes
+takumi needs bash to run. Git for Windows includes it. Make sure [Git for Windows](https://git-scm.com/download/win) is installed — the default installation options are fine.
 
-- All commands support single files or folders (recursive)
-- Existing outputs are skipped on re-run (safe to retry)
-- Converted videos get a `_firetv` suffix
-- Captions are saved next to the source video
+### ffmpeg not found after setup
 
-## Update
+Restart your terminal. If it still doesn't work, check that ffmpeg is installed:
 
 ```bash
-# Homebrew
-brew update && brew upgrade takumi
+ffmpeg -version
+```
 
-# npm
-npm update -g takumi-cli
+On Windows, you can install it manually with:
+
+```powershell
+winget install --id Gyan.FFmpeg -e
 ```
+
+## License
+
+MIT

package/commands/mcp-config.sh

@@ -11,7 +11,35 @@ cmd_mcp-config() {
     return 1
   fi
 
-  echo "Add this to your MCP settings (Claude Code, Kiro, etc.):"
+  echo "── VS Code (.vscode/mcp.json) ──"
+  echo ""
+  cat <<EOF
+{
+  "servers": {
+    "takumi": {
+      "command": "node",
+      "args": ["${MCP_SERVER}"]
+    }
+  }
+}
+EOF
+
+  echo ""
+  echo "── Claude Code (~/.claude.json or .mcp.json) ──"
+  echo ""
+  cat <<EOF
+{
+  "mcpServers": {
+    "takumi": {
+      "command": "node",
+      "args": ["${MCP_SERVER}"]
+    }
+  }
+}
+EOF
+
+  echo ""
+  echo "── Kiro (.kiro/settings/mcp.json) ──"
   echo ""
   cat <<EOF
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takumi-cli",
-  "version": "1.2.0",
+  "version": "1.2.3",
   "description": "The craftsman's toolkit for shaping video assets",
   "bin": {
     "takumi": "bin/takumi.js"