junara/j-guide-video

Illustrated Procedure Video (Guide Layout)

One step of the procedure = one scene. In sync with the narration phrases, pick up a tool, pour, open, tap, and assemble. Drawing, audio, and export are all done with Swift (CoreGraphics, AVFoundation), and the CLI jgv handles the script, audio, subtitles, still images, and video export.

• <skill> is the directory of this SKILL.md (${CLAUDE_SKILL_DIR}. If not available, use ${CLAUDE_PLUGIN_ROOT}/.claude/skills/j-guide-video when installed via plugin, otherwise ~/.claude/skills/j-guide-video or .claude/skills/j-guide-video, whichever exists)
• jgv below refers to <skill>/bin/jgv. The first time, and after updating the skill, it takes several tens of seconds to a few minutes to build itself and the kit (drawing DSL and components) in Swift. The build is cached (in ~/Library/Caches/j-guide-video/); the video project only contains topic-specific files (script, binding, cues, SVG assets). The mechanism is described in reference/environment.md. If the user asks to clear the cache, run jgv clean --stale --dry-run to show what will be deleted, then jgv clean --stale. To clear everything, use the default location: rm -rf ~/Library/Caches/j-guide-video (it will be rebuilt on the next build). If the location is changed with J_GUIDE_VIDEO_CACHE, do not delete the whole folder; only delete build-*, shared-*, projects, and avtts inside it (because the folder may not be dedicated)
• Arguments and options are available via jgv help <subcommand>. Unknown options result in an error.
• <library> is the user's library (environment variable J_GUIDE_VIDEO_LIBRARY, or ~/.config/j-guide-video if not set; under $XDG_CONFIG_HOME if that is set). Tools and motions (parts/) and preference settings (defaults.json) from previous videos are stored here and are not deleted when the skill is updated (see reference/library.md)

procedure.md ─(jgv new = init・md2script --stubs・tts・timing)→ script.json・cue and binding templates・audio・timeline・subtitles・time table
visuals/bind.swift (tool/screen drawing and naming) + cues/<Step>.cue (phrase-by-phrase motions) ─(jgv check → jgv dev → jgv render → jgv overview)→ out/video.mp4

Things to confirm first

Operating environment

• macOS only (version that runs the latest Xcode; confirmed only on Apple Silicon; Intel Macs not tested), exclusively for Claude Code. Tell the user it cannot be used on Linux, Windows (including WSL2), Claude Code on the web, or Claude.ai, and stop
• Requires the latest Xcode or Command Line Tools (swift via xcode-select --install; older versions not verified). jgv will stop if these are missing or outdated, so instruct the user on installation (do not run commands requiring sudo without asking). Initial jgv build needs network access
• Narration defaults to macOS voices ("voice": "auto" selects the highest quality voice for the script's language; list available with jgv voices)
• Commercially usable TTS includes built-in cloud TTS and an arbitrary command-based command engine. Cloud TTS is ready by setting environment variable keys: google (GOOGLE_TTS_API_KEY; for service account keys, GOOGLE_APPLICATION_CREDENTIALS), azure (AZURE_SPEECH_KEY and AZURE_SPEECH_REGION), amazon (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION), openai (OPENAI_API_KEY; model support ends 2027-01-06, not recommended for long-term videos)
• API keys and scripts are provided by the user. Claude must not input or display API keys, open service account key files (GOOGLE_APPLICATION_CREDENTIALS), or call paid APIs without authorization
• When handling a video project not created by the user (a zip file, someone else's repository, or a script passed via --base), before running jgv check with the user the tts settings in script.json and any script.<language>.json (whether the engine is a paid cloud TTS or what is written in command), and confirm the existence of Swift files in visuals/, parts/, and kit/. Commands jgv tts / timing / dev / check / snapshots / still / preview / catalog / render / build-langs (all commands that generate audio, build and draw visuals) run those commands and code as-is
• Paid cloud TTS is not invoked until you confirm once per project and engine with jgv tts --allow-cloud (jgv tts first prints line/character counts and stops). Only use --allow-cloud after informing the user about the engine and cost and getting their OK (jgv new --tts … and scripts created with jgv new using the library's defaults.json engine are automatically authorized. When inheriting a cloud engine from someone else's script via jgv new --base, jgv new stops before creating anything and tells the user to choose with --tts)
• Voice, speed, per-TTS settings, disk/cache mechanisms: see reference/environment.md

Usage conditions for generated videos

• macOS voices (default apple): Apple's macOS license ("Voices" section) permits use of system voices only for creating your own original works for personal, non-commercial purposes. Exported videos are limited to personal, non-commercial use; they cannot be published on social media/video sites, or used for work/corporate purposes (which seems to include internal company manuals). (Summary; refer to the "Voices" section of the macOS license)
• TTS connected via google / azure / amazon / openai / command: Follow the terms of use of that TTS service. If the TTS allows commercial use, it can be used for publication or business. If the TTS requires credit or a statement that it is AI-generated, write that in the credit field of script.json
• If the request appears to be for publication on social media/video sites or for work/corporate use, inform the user before starting work, and tell them they can switch to a commercially usable TTS. Do not make legal judgments (instruct them to check Apple's license or the TTS provider's terms)

0. Choose the video layout

Based on the topic, choose the layout and briefly tell the user (only ask if unsure). The project location (2's <dir>) should also be mentioned here.

Layout	--layout	Appearance	Suitable topics	Examples (examples/)
Room	guide (default)	A character stands in a room, uses tools. Close-up of hands via magnified card	Drinks, chores, appliance care – "a person handling tools"	room-microwave-rice, room-mug-wash
Screen	guide-screen	No character. Tap/click/type on a smartphone/browser screen. Point notes on the right, dimming non-essential areas	App/web service operation procedures	screen-alarm (smartphone)
Top-down	guide-topdown	Overhead view of a workbench; both hands extend from the bottom of the screen	Cooking, crafts, wrapping – actions focused on hands	topdown-cucumber
Manual	guide-manual	White graph paper with isometric line drawings, dotted arrows, screw tightening, parts list	Furniture assembly, equipment installation, part replacement	manual-smallbox
Vertical	any of the above + --vertical	1080×1920. For the room layout, character at top, magnified card always visible below the counter (confirmed only for the room layout)	Short life hacks, recipes viewed vertically on a smartphone	vertical-coffee

Even if multi-language versions are needed, first complete one language, then add them in "6. Create multi-language versions".

1. Prepare the procedure document

Compile the user's text into the following Markdown format and save it as <dir>/procedure.md (use as-is if already in this format).

# How to Brew Drip Bag Coffee
## Get ready [prepare]
Prepare a mug, a drip coffee bag and a kettle. Boil the water and let it cool to about ninety degrees Celsius.
## Open the bag [open]
Hold the bag with both hands, tear off the top strip along the marked line. Open it gently to avoid spilling the coffee.

• # Title, ## Step name [tag], the body text is read as-is. The tag is optional and becomes the visual name (open → Open). Must be alphanumeric starting with a letter, can contain - and _. Otherwise it is ignored and becomes something like Step01
• Bullet points and numbered lists: one item = one sentence. Emphasis, links, and inline code notation are removed for reading (HTML tags, comments, and code blocks are not read. Key names like <Enter> and angle brackets for placeholders are kept). For Japanese and Chinese, line breaks are also sentence boundaries (a line ending with a comma connects to the next line). For English etc., blank lines separate paragraphs. Add a period at the end of a sentence if missing. Tables (| … | lines) and code blocks are not read (a warning is shown if a table is excluded)
• Aim for 4 to 8 steps, 1 to 3 sentences per step. 1 sentence = 1 animation segment; a comma (,) = an even finer segment. Write sentences where "what → do what" is separated by phrases (e.g., "Spread the paper hooks, attach them to the rim of your mug.")
• Write with the assumption that actual waiting times (steeping, drying) are shortened in the video
• If the user's text is free-form (notes, manuals), rewrite it into the procedure format based on the guidelines in reference/rewriting.md

2. Create the project and convert to script

jgv new <dir> --kicker "DAILY RITUAL / COFFEE GUIDE" --layout guide

jgv new does the following in one command: creates the project (jgv init), generates script and cue templates (jgv md2script procedure.md -o script.json --stubs visuals), generates speech audio and timeline (jgv tts), and prints the cue timing table (jgv timing; shows line.phrase and seconds from the start of each step). The procedure document is taken from <dir>/procedure.md (if it is elsewhere, pass it with jgv new <dir> <procedure.md> to copy it). Options are the same as jgv md2script. Subsequent commands should be run after cd <dir>.

• <dir>: use the location specified by the user. If not specified, do not ask; create it outside the skill and its repository (e.g., ~/Movies/jgv/<topic>). In either case, before creating (when telling the layout in step 0), inform the user of the full path (e.g., "Creating it in ~/Movies/jgv/shoulder-massage. Let me know if you want a different location."). Creating under the current directory may put generated files (out/, .jgv/) inside the repository
• --layout is the layout chosen in step 0. For vertical, add --vertical. --kicker is the series name in the upper left
• Presenter appearance (--presenter), relationship with library defaults.json, cloud TTS (--tts), suppressing text (--no-text, etc.), migrating older project formats (jgv migrate): see reference/options.md "jgv new options". If defaults.json has kicker/layout, only add --kicker/--layout when the user specifies something different from what is in defaults.json or from the layout chosen in step 0
• If jgv new stops with an error, it cleans up what it created and reverts (pre-existing files remain). Fix the cause and rerun the same jgv new (if interrupted, see troubleshooting in reference/tips.md)

Outputs (fully functional at this point): script.json, cues/<Visual>.cue per step (with line.phrase numbers and sentence annotations at the top), visuals/<Visual>.swift (a single line calling the cue – do not touch), visuals/bind.swift (binding template), .jgv/timeline.json, out/subtitles.srt.

Adjust Japanese reading

• For Japanese, in the speak field of each line in script.json, rewrite numbers, English words, and hard-to-read words for better pronunciation. Write the reading in katakana (hiragana may merge with adjacent hiragana, causing mis-segmentation. E.g., "食欲やはいせつぶつ" → "や/は/いせつ…". Writing ハイセツブツ avoids this)
• Use jgv yomi to view per-word readings and warnings, and fix any unintended readings. jgv yomi uses macOS analysis regardless of the TTS engine, so treat it as a guide for cloud TTS (katakana conversion works for any engine). See reference/tips.md "Japanese readings" for warning types and corrections
• After fixing speak, run jgv tts (re-reads only the changed lines) then jgv timing (re-outputs the timing table)
• If the user points out a reading issue, ask in step 7 whether to add it to the library's defaults.json under readings

3. Decide tools and screens (binding)

For each step, determine the objects (tools, devices, screens) to show, their placement, and where the hands touch them. Write this as binding in visuals/bind.swift (for which jgv new creates a template). One binding file applies to all steps. See reference/cue.md "binding" for the syntax.

• Before writing, read one example of the same layout type (choose from examples/README.md and read its visuals/bind.swift and cues/*.cue. Copy similar motions and placements from there)
• Prefer components from the kit and parts/ in the project (or the library). For available appearances, read reference/props-catalog.png; for a list, see reference/visual-kit.md "Tool list". Look up arguments and grip points (e.g., KETTLE_PARTS) with jgv api やかん (supports names, Japanese names, and descriptive terms; jgv api alone lists all names; project's parts/ is also included). Do not grep kit sources
• If a tool is missing, draw it in visuals/props.swift following the rules in reference/prop-style.md, and verify with jgv preview using PROPS_PREVIEW. If the user has an SVG, place it in assets/ and use Svg("name") (see visual-kit.md "SVG assets (assets)")
• Use named constants for tool positions and scales (e.g., let MW = Pt(1080, GUIDE.counterY). For vertical, use LAYOUT_PORTRAIT.counterY). This makes adjustments easier
• Place tools/devices that the character touches with hands close to the character (within about x 1150 for landscape layouts) (jgv check warns if the hand is too far)
• For steps like "What you need", "Note", "Before/After", "Summary", you can use the kit's scene types (PrepareItems, NoteCards, BeforeAfter, SummaryList) in the binding drawing
• Layout-specific visual guidelines: see reference/implementation.md "Layout-specific points"

4. Write step motions in cue files

Write cues/<Visual>.cue for each step. The line.phrase time numbers come from the annotations at the top of the template (# 0.0 冷凍ごはんを、 0.1 ラップのまま、…) and the timing table from jgv new / jgv timing. Syntax: reference/cue.md. Copy similar motions from examples of the same layout (see examples/). Each cue file is only a few to a dozen lines, so write all steps in the main flow without using sub-agents per step.

init <Load
0.0+.3 H>mw.handle~.45
0.0+.35 mw.open=0~.6
0.2+.45 P mw.start;mw.on=1~.2;mw.disp=cd 2:00 0:[email protected];timer timer 2分@1.0
1.1+.7 H>dish.gripL~.4;dish.in=0
1.1+.77 dish@PLATE~.5;steam dish.top

• Write one line per phrase with "what → do what" (animate the noun/verb at the time the phrase is read). For waiting times, use an arc timer (timer) and the annotation "Waiting time is shortened"
• **Hand (H>, C>, P): time the hand arrives. Other elements: time the motion starts. When aligning values with hand motion, offset the value's start time by the hand's movement duration
• For subsequent steps, start with init <previous step (to inherit the final state). To keep a magnified card open across steps, set card.exit=0 in the previous step and card.enter=0 in the next
• Show fine handwork (opening, scooping, rubbing, twisting) in the magnified card (card, C>). The character points from the left (H>gesture). The final step should show the finished product + check mark + steam/sparkle lingering
• Avoid static screens: during narration, keep things moving (steam, wave, ripples, etc.)

cd <dir> && jgv check

Fix cues and binding until there are no ! lines (name errors, hand too far, releasing an object while moving it, motion later than 0.5 seconds before the end, overlapping text/frames, etc.). Lines H/C show the hand timing table (which second to which second, from where to where). Lines S1→S2 show differing values at step boundaries (only intentionally changed values should appear). When only cues are changed, no rebuild is needed, so rechecking is fast. For line explanations and fixes, see cue.md "jgv check".

For special motions that cannot be described in cues, write them in Swift in the binding drawing and control them by value from the cue (see cue.md "Writing in Swift"). An alternative approach (storyboard → parallel implementation by step agents) is also available (see reference/implementation.md).

5. Full review → Export

cd <dir> && jgv dev

jgv dev performs all checks in one pass: jgv tts (re-reads only changed lines) → build → jgv check (stops if there are ! lines) → jgv snapshots (only for steps changed since the last jgv dev).

• Compilation errors (e.g., in binding) appear with file name and line number: visuals/bind.swift:12:5: error: …
• The final line "Images to check:" lists the files to read. For the first run, after changing Swift files, assets/, color schemes, or if all steps changed: the full sheet out/snapshots/sheet.png. If only cues changed: the changed step's sheet out/snapshots/scene-N/sheet.png (including steps that inherit the state via init <previous step). Changing the script usually changes video length and progress bar, requiring a full re-snapshot. Rerun all snapshots with jgv dev --all
• Always open and review the images listed in "Images to check:"; then fix and rerun jgv dev (if only some steps were re-snapped, the old full out/snapshots/sheet.png remains – do not confuse them). Use the hand timing table from jgv check (not images) to spot hand timing errors quickly
• For small details invisible in the sheet (dotted lines, annotation text, hand/grip positions), read individual still frames from the same folder (half the video size; filenames correspond to the numbers shown at the head of each line during export, e.g., 03.png. For per-phrase snapshots with jgv snapshots --scene=N --phrases, the file is 02-04.png. Note: jgv dev does not support --phrases)

Check in images:

• Is the hand attached to the tool's grip? Are tools floating or overlapping?
• Does the on-screen action match the phrase content? (e.g., in a "tear off" line, is the strip actually tearing?)
• Are the magnified card's step labels and annotations readable? For overlapping text/annotations/frames or elements going off-screen, jgv check outputs lines starting with ! 秒-秒s:. In images, focus on object-object overlap, double-drawn objects, and whether the binding visual overlaps the title/subtitle bar (check does not catch this). If --no-text or --no-notes is used, verify the explanatory text is not shown.

If everything looks good, export and create the overview page:

cd <dir> && jgv render && jgv overview

out/overview.html shows all step narrations, visual files, stills, and SVG assets on one page (open in a browser). Inform the user of the locations of out/video.mp4, out/subtitles.srt, and out/overview.html. Send the video if the environment allows it. Then proceed to step 7 "Save to library".

For adjustments (color, voice), error handling, and Swift implementation examples (in the demo/ repository), see reference/tips.md.

6. Create multi-language versions

After completing the first language, follow the steps in reference/multilang.md to add script.<language>.json files, then run jgv build-langs to export all versions at once (the video is shared; only the script and on-screen text are swapped).

7. Save to library

After exporting, list candidates to save to the library: tools and motions created for this video that could be reused for other topics (visuals/props.swift, shared.swift, tool drawing code written in binding), user-chosen preferences (color scheme, voice, speed, etc., excluding per-topic kickers), and readings corrected per user feedback (readings). Ask the user whether to save these to the library (if there are no candidates or all are already in the library, do not ask). When saving, follow the steps in reference/library.md "Save after video completion" to place them in <library>/parts/ and <library>/defaults.json. This reduces drawing and configuration effort for future videos.