PV Tool Skill

Use this skill to operate the vendored pv-tool application in app/.

What this skill is for

• Start the local PV Tool dev server
• Build the bundled app
• Preview the production build
• Use the app for lyric-video and kinetic-typography workflows

Important license note

The bundled upstream app in app/ is not under a generic permissive license.

• Non-commercial use only by default
• Commercial use requires a separate license from the upstream author
• Check app/LICENSE and app/COMMERCIAL.md before using it for paid work

If the user asks to use PV Tool for a commercial workflow, call out this restriction explicitly.

Runtime requirements

• Node.js 20+
• npm

Commands

Run commands from skills/pv-tool/:

bash scripts/bootstrap.sh
bash scripts/dev.sh
bash scripts/build.sh
bash scripts/preview.sh

Environment overrides:

PV_TOOL_DEV_HOST=0.0.0.0
PV_TOOL_DEV_PORT=4173
PV_TOOL_PREVIEW_HOST=127.0.0.1
PV_TOOL_PREVIEW_PORT=4174
VITE_BASE=/pv-tool/

Standard workflow

1. Run bash scripts/bootstrap.sh to install dependencies into app/node_modules.
2. Run bash scripts/dev.sh for local editing and experimentation.
3. Open the reported local URL and use the UI.
4. Run bash scripts/build.sh when the user wants a production build.
5. Run bash scripts/preview.sh to verify the built output in a browser.

In-app usage

• Start from a preset template or switch to Custom
• Enter text with / as the segment separator
• Load an image or video as the background media layer
• Load audio for BPM and beat-reactive effects
• Import .lrc files for lyric timing
• Adjust post-FX such as shake, zoom, tilt, glitch, and hue shift
• Use the built-in recording/export controls when the user needs captured output

Agent behavior

• Prefer running the provided scripts instead of manually restating npm commands.
• When starting dev.sh or preview.sh, report the exact local URL.
• Keep long-running server processes attached unless the user asks to daemonize them.
• If dependencies are missing, let the wrapper scripts install them first.
• If Node.js is too old, stop and tell the user to upgrade before proceeding.

File layout

• app/ — vendored upstream PV Tool source
• scripts/bootstrap.sh — dependency installation
• scripts/dev.sh — local Vite dev server
• scripts/build.sh — production build
• scripts/preview.sh — local preview server