/motiscope-doctor

name: motiscope-doctor
description: 'Check and configure motiscope — verify ffmpeg/ffprobe are installed and scaffold the API-key config used for optional (stubbed) asset generation. Use for first-time setup, "motiscope isn''t working", dependency errors, or `motiscope-doctor`.'

motiscope: doctor

> Check and configure motiscope — verify ffmpeg/ffprobe are installed and scaffold the API-key config used for optional (stubbed) asset generation. Use for first-time setup, "motiscope isn't working", dependency errors, or `motiscope-doctor`.

Running motiscope

`motiscope` is a shell command. If it isn't found it isn't on your PATH — see https://github.com/KumarSashank/motiscope#install. The reference guides live under `$(motiscope home)/references/`.

**Invoking the sibling skills.** In Codex, mention a skill with `$motiscope-recreate`. In Cursor, use `/motiscope-recreate`. Elsewhere, just follow that skill's `SKILL.md`.

**Seeing the frames — do not skip this.** The curated keyframes are PNG files on disk, and you must actually look at them. Codex: use the `view_image` tool (if it's unavailable, enable `tools.view_image = true` in `~/.codex/config.toml`, or have the user relaunch with `codex -i frame1.png,frame2.png`). Cursor: the file-reading tool accepts `.png` and puts the image in context. If you genuinely cannot open images, **say so** — you can still report the measured timing, but you cannot know *what* is animating, and you must not guess it from the filenames.

Verify dependencies and scaffold config. motiscope's pipeline is pure Python standard library, so the only hard dependencies are **ffmpeg** and **ffprobe**.

Run status

motiscope doctor --json

The JSON reports `status`, `missing_binaries`, `install_hint`, `platform`, `config_file`, `env_file`, and per-provider key presence.

If ffmpeg/ffprobe are missing

Do **not** install silently. Ask the user for permission, then run the platform command:

• **macOS (Homebrew):** `brew install ffmpeg`
• **Linux:** `sudo apt-get install -y ffmpeg` (or `sudo dnf install ffmpeg`)
• **Windows:** `winget install Gyan.FFmpeg` (or `choco install ffmpeg`)

Re-run `mvsetup.py --check` afterward to confirm (exit 0 = ready).

Scaffold config

motiscope doctor

This creates, if absent:

• `~/.config/motiscope/config.json` — non-secret preferences (`default_target`, `frame_budget`, `resolution`, `frame_format`, `image_provider`, `video_provider`).
• `~/.config/motiscope/.env` (mode `0600`) — **optional** API keys for asset generation, commented out by default.

API keys (optional)

Asset generation (creating an image an animation needs) is **optional** — no key is required for analysis or code recreation. Image generation is real for **Gemini/Imagen**; the other providers write a labeled placeholder until wired. To configure one, ask the user which provider, and write the key into `~/.config/motiscope/.env`:

| Purpose | Providers (env var) | |---|---| | Image | **Gemini/Imagen (`GEMINI_API_KEY`) — implemented**; OpenAI (`OPENAI_API_KEY`), Stability (`STABILITY_API_KEY`), Replicate (`REPLICATE_API_TOKEN`), fal (`FAL_KEY`) | | Video | Runway (`RUNWAY_API_KEY`), Replicate (`REPLICATE_API_TOKEN`), fal (`FAL_KEY`) |

Image generation works today with **`gemini`** (Imagen). Other providers write a labeled placeholder until wired.

Reassure the user: keys stay in a local `0600` file, are never printed, never written into generated code, and never committed (the repo `.gitignore` excludes `.env`).

Report back

Summarize: dependency status, what was scaffolded, and whether any provider keys are configured. If everything is ready, say so in one line and point them at ``motiscope-analyze``.