Add files using upload-large-folder tool
Browse filesThis view is limited to 50 files because it contains too many changes. See raw diff
- optional-skills/blockchain/hyperliquid/scripts/hyperliquid_client.py +1660 -0
- optional-skills/creative/ai-presenter-video/LICENSE +21 -0
- optional-skills/creative/ai-presenter-video/SKILL.md +196 -0
- optional-skills/creative/ai-presenter-video/assets/job.template.json +83 -0
- optional-skills/creative/ai-presenter-video/references/editing.md +65 -0
- optional-skills/creative/ai-presenter-video/references/generation.md +83 -0
- optional-skills/creative/ai-presenter-video/references/qa-recovery.md +73 -0
- optional-skills/creative/ai-presenter-video/scripts/finalize_delivery.sh +166 -0
- optional-skills/creative/ai-presenter-video/scripts/init_job.py +151 -0
- optional-skills/creative/ai-presenter-video/scripts/preflight.py +177 -0
- optional-skills/creative/archify/SKILL.md +52 -0
- optional-skills/creative/ascii-art/SKILL.md +322 -0
- optional-skills/creative/audiocraft-audio-generation/SKILL.md +569 -0
- optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md +666 -0
- optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md +504 -0
- optional-skills/creative/baoyu-article-illustrator/PORT_NOTES.md +48 -0
- optional-skills/creative/baoyu-article-illustrator/SKILL.md +207 -0
- optional-skills/creative/baoyu-article-illustrator/prompts/system.md +32 -0
- optional-skills/creative/baoyu-article-illustrator/references/palettes/macaron.md +33 -0
- optional-skills/creative/baoyu-article-illustrator/references/palettes/mono-ink.md +42 -0
- optional-skills/creative/baoyu-article-illustrator/references/palettes/neon.md +33 -0
- optional-skills/creative/baoyu-article-illustrator/references/palettes/warm.md +32 -0
- optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md +426 -0
- optional-skills/creative/baoyu-article-illustrator/references/style-presets.md +80 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles.md +224 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/blueprint.md +57 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/chalkboard.md +62 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/editorial.md +59 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/elegant.md +56 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/fantasy-animation.md +58 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/flat-doodle.md +61 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/flat.md +59 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/ink-notes.md +90 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/intuition-machine.md +57 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/minimal.md +58 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/nature.md +58 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/notion.md +58 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/pixel-art.md +57 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/playful.md +59 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/retro.md +59 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/scientific.md +59 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/screen-print.md +70 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/sketch-notes.md +56 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/sketch.md +57 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/vector-illustration.md +57 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/vintage.md +59 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/warm.md +58 -0
- optional-skills/creative/baoyu-article-illustrator/references/styles/watercolor.md +58 -0
- optional-skills/creative/baoyu-article-illustrator/references/usage.md +50 -0
- optional-skills/creative/baoyu-article-illustrator/references/workflow.md +332 -0
optional-skills/blockchain/hyperliquid/scripts/hyperliquid_client.py
ADDED
|
@@ -0,0 +1,1660 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
#!/usr/bin/env python3
|
| 2 |
+
"""
|
| 3 |
+
Hyperliquid CLI Tool for Hermes Agent
|
| 4 |
+
-------------------------------------
|
| 5 |
+
Queries the Hyperliquid info endpoint for market and account data.
|
| 6 |
+
Uses only Python standard library - no external packages required.
|
| 7 |
+
|
| 8 |
+
Usage:
|
| 9 |
+
python3 hyperliquid_client.py dexs
|
| 10 |
+
python3 hyperliquid_client.py markets [--dex DEX] [--limit N]
|
| 11 |
+
python3 hyperliquid_client.py spots [--limit N]
|
| 12 |
+
python3 hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24]
|
| 13 |
+
python3 hyperliquid_client.py funding <coin> [--hours 72]
|
| 14 |
+
python3 hyperliquid_client.py l2 <coin> [--levels 10]
|
| 15 |
+
python3 hyperliquid_client.py state [address] [--dex DEX]
|
| 16 |
+
python3 hyperliquid_client.py spot-balances [address]
|
| 17 |
+
python3 hyperliquid_client.py fills [address] [--hours N] [--limit N]
|
| 18 |
+
python3 hyperliquid_client.py orders [address] [--limit N]
|
| 19 |
+
python3 hyperliquid_client.py review [address] [--coin COIN] [--hours N]
|
| 20 |
+
python3 hyperliquid_client.py export <coin> [--interval 1h] [--hours N]
|
| 21 |
+
|
| 22 |
+
Environment:
|
| 23 |
+
HYPERLIQUID_API_URL Override API base URL
|
| 24 |
+
(default: https://api.hyperliquid.xyz)
|
| 25 |
+
HYPERLIQUID_USER_ADDRESS Default address for state/fills/orders/review commands
|
| 26 |
+
"""
|
| 27 |
+
|
| 28 |
+
from __future__ import annotations
|
| 29 |
+
|
| 30 |
+
import argparse
|
| 31 |
+
import datetime as dt
|
| 32 |
+
import json
|
| 33 |
+
import os
|
| 34 |
+
import sys
|
| 35 |
+
import time
|
| 36 |
+
import urllib.error
|
| 37 |
+
import urllib.request
|
| 38 |
+
from collections import Counter
|
| 39 |
+
from pathlib import Path
|
| 40 |
+
from typing import Any, Dict, Iterable, List, Optional
|
| 41 |
+
|
| 42 |
+
|
| 43 |
+
USER_AGENT = "HermesAgent/1.0"
|
| 44 |
+
DEFAULT_USER_ENV = "HYPERLIQUID_USER_ADDRESS"
|
| 45 |
+
DEFAULT_API_BASE = "https://api.hyperliquid.xyz"
|
| 46 |
+
|
| 47 |
+
|
| 48 |
+
def _hermes_home() -> Path:
|
| 49 |
+
return Path(os.environ.get("HERMES_HOME", "~/.hermes")).expanduser()
|
| 50 |
+
|
| 51 |
+
|
| 52 |
+
def _dotenv_paths() -> List[Path]:
|
| 53 |
+
paths: List[Path] = []
|
| 54 |
+
project_env = Path.cwd() / ".env"
|
| 55 |
+
if project_env.exists():
|
| 56 |
+
paths.append(project_env)
|
| 57 |
+
|
| 58 |
+
user_env = _hermes_home() / ".env"
|
| 59 |
+
if user_env.exists():
|
| 60 |
+
paths.append(user_env)
|
| 61 |
+
|
| 62 |
+
return paths
|
| 63 |
+
|
| 64 |
+
|
| 65 |
+
def _load_dotenv_values() -> Dict[str, str]:
|
| 66 |
+
values: Dict[str, str] = {}
|
| 67 |
+
for env_path in _dotenv_paths():
|
| 68 |
+
try:
|
| 69 |
+
lines = env_path.read_text(encoding="utf-8").splitlines()
|
| 70 |
+
except UnicodeDecodeError:
|
| 71 |
+
lines = env_path.read_text(encoding="latin-1").splitlines()
|
| 72 |
+
|
| 73 |
+
for raw_line in lines:
|
| 74 |
+
line = raw_line.strip()
|
| 75 |
+
if not line or line.startswith("#") or "=" not in line:
|
| 76 |
+
continue
|
| 77 |
+
key, _, value = raw_line.partition("=")
|
| 78 |
+
key = key.strip()
|
| 79 |
+
value = value.strip()
|
| 80 |
+
if value.startswith('"') and value.endswith('"') and len(value) >= 2:
|
| 81 |
+
value = value[1:-1].replace('\\"', '"').replace('\\\\', '\\')
|
| 82 |
+
values[key] = value
|
| 83 |
+
return values
|
| 84 |
+
|
| 85 |
+
|
| 86 |
+
def _env_lookup(key: str, default: str = "") -> str:
|
| 87 |
+
value = os.environ.get(key, "").strip()
|
| 88 |
+
if value:
|
| 89 |
+
return value
|
| 90 |
+
dotenv_value = _load_dotenv_values().get(key, "").strip()
|
| 91 |
+
if dotenv_value:
|
| 92 |
+
return dotenv_value
|
| 93 |
+
return default
|
| 94 |
+
|
| 95 |
+
|
| 96 |
+
def _api_base() -> str:
|
| 97 |
+
return _env_lookup("HYPERLIQUID_API_URL", DEFAULT_API_BASE).rstrip("/")
|
| 98 |
+
|
| 99 |
+
|
| 100 |
+
def _info_url() -> str:
|
| 101 |
+
api_base = _api_base()
|
| 102 |
+
if api_base.endswith("/info"):
|
| 103 |
+
return api_base
|
| 104 |
+
return f"{api_base}/info"
|
| 105 |
+
|
| 106 |
+
|
| 107 |
+
def _resolve_user(user: Optional[str]) -> str:
|
| 108 |
+
candidate = (user or "").strip()
|
| 109 |
+
if candidate:
|
| 110 |
+
return candidate
|
| 111 |
+
|
| 112 |
+
env_value = _env_lookup(DEFAULT_USER_ENV, "")
|
| 113 |
+
if env_value:
|
| 114 |
+
return env_value
|
| 115 |
+
|
| 116 |
+
sys.exit(
|
| 117 |
+
"Missing Hyperliquid address. Pass <address> explicitly or set "
|
| 118 |
+
f"{DEFAULT_USER_ENV} in your environment or {_hermes_home() / '.env'}."
|
| 119 |
+
)
|
| 120 |
+
|
| 121 |
+
|
| 122 |
+
def _post_info(payload: Dict[str, Any], timeout: int = 20, retries: int = 2) -> Any:
|
| 123 |
+
data = json.dumps(payload).encode("utf-8")
|
| 124 |
+
headers = {
|
| 125 |
+
"Content-Type": "application/json",
|
| 126 |
+
"Accept": "application/json",
|
| 127 |
+
"User-Agent": USER_AGENT,
|
| 128 |
+
}
|
| 129 |
+
|
| 130 |
+
for attempt in range(retries + 1):
|
| 131 |
+
request = urllib.request.Request(_info_url(), data=data, headers=headers, method="POST")
|
| 132 |
+
try:
|
| 133 |
+
with urllib.request.urlopen(request, timeout=timeout) as response:
|
| 134 |
+
body = json.load(response)
|
| 135 |
+
return body
|
| 136 |
+
except urllib.error.HTTPError as exc:
|
| 137 |
+
if exc.code == 429 and attempt < retries:
|
| 138 |
+
time.sleep(1.5 * (attempt + 1))
|
| 139 |
+
continue
|
| 140 |
+
sys.exit(f"Hyperliquid HTTP error: {exc}")
|
| 141 |
+
except urllib.error.URLError as exc:
|
| 142 |
+
sys.exit(f"Hyperliquid connection error: {exc}")
|
| 143 |
+
except json.JSONDecodeError as exc:
|
| 144 |
+
sys.exit(f"Hyperliquid response was not valid JSON: {exc}")
|
| 145 |
+
|
| 146 |
+
return None
|
| 147 |
+
|
| 148 |
+
|
| 149 |
+
def _safe_float(value: Any) -> Optional[float]:
|
| 150 |
+
try:
|
| 151 |
+
if value is None or value == "":
|
| 152 |
+
return None
|
| 153 |
+
return float(value)
|
| 154 |
+
except (TypeError, ValueError):
|
| 155 |
+
return None
|
| 156 |
+
|
| 157 |
+
|
| 158 |
+
def _limit_items(items: List[Dict[str, Any]], limit: int) -> List[Dict[str, Any]]:
|
| 159 |
+
if limit <= 0:
|
| 160 |
+
return items
|
| 161 |
+
return items[:limit]
|
| 162 |
+
|
| 163 |
+
|
| 164 |
+
def _hours_ago_ms(hours: float, now_ms: Optional[int] = None) -> int:
|
| 165 |
+
end_ms = now_ms if now_ms is not None else int(time.time() * 1000)
|
| 166 |
+
return end_ms - int(hours * 60 * 60 * 1000)
|
| 167 |
+
|
| 168 |
+
|
| 169 |
+
def _format_timestamp_ms(value: Any) -> str:
|
| 170 |
+
try:
|
| 171 |
+
ts_ms = int(value)
|
| 172 |
+
except (TypeError, ValueError):
|
| 173 |
+
return "-"
|
| 174 |
+
return dt.datetime.utcfromtimestamp(ts_ms / 1000).strftime("%Y-%m-%d %H:%M:%S UTC")
|
| 175 |
+
|
| 176 |
+
|
| 177 |
+
def _compact_number(value: Any, decimals: int = 2) -> str:
|
| 178 |
+
number = _safe_float(value)
|
| 179 |
+
if number is None:
|
| 180 |
+
return "-"
|
| 181 |
+
sign = "-" if number < 0 else ""
|
| 182 |
+
number = abs(number)
|
| 183 |
+
if number >= 1_000_000_000:
|
| 184 |
+
return f"{sign}{number / 1_000_000_000:.{decimals}f}B"
|
| 185 |
+
if number >= 1_000_000:
|
| 186 |
+
return f"{sign}{number / 1_000_000:.{decimals}f}M"
|
| 187 |
+
if number >= 1_000:
|
| 188 |
+
return f"{sign}{number / 1_000:.{decimals}f}K"
|
| 189 |
+
if number >= 100:
|
| 190 |
+
return f"{sign}{number:.2f}"
|
| 191 |
+
if number >= 1:
|
| 192 |
+
return f"{sign}{number:.4f}".rstrip("0").rstrip(".")
|
| 193 |
+
return f"{sign}{number:.6f}".rstrip("0").rstrip(".")
|
| 194 |
+
|
| 195 |
+
|
| 196 |
+
def _format_price(value: Any) -> str:
|
| 197 |
+
number = _safe_float(value)
|
| 198 |
+
if number is None:
|
| 199 |
+
return "-"
|
| 200 |
+
if abs(number) >= 1000:
|
| 201 |
+
return f"{number:,.2f}"
|
| 202 |
+
if abs(number) >= 1:
|
| 203 |
+
return f"{number:,.4f}".rstrip("0").rstrip(".")
|
| 204 |
+
return f"{number:,.6f}".rstrip("0").rstrip(".")
|
| 205 |
+
|
| 206 |
+
|
| 207 |
+
def _format_percent(value: Any, decimals: int = 2) -> str:
|
| 208 |
+
number = _safe_float(value)
|
| 209 |
+
if number is None:
|
| 210 |
+
return "-"
|
| 211 |
+
return f"{number:+.{decimals}f}%"
|
| 212 |
+
|
| 213 |
+
|
| 214 |
+
def _format_fraction_percent(value: Any, decimals: int = 4) -> str:
|
| 215 |
+
number = _safe_float(value)
|
| 216 |
+
if number is None:
|
| 217 |
+
return "-"
|
| 218 |
+
return f"{number * 100:+.{decimals}f}%"
|
| 219 |
+
|
| 220 |
+
|
| 221 |
+
def _percent_change(current: Any, previous: Any) -> Optional[float]:
|
| 222 |
+
curr = _safe_float(current)
|
| 223 |
+
prev = _safe_float(previous)
|
| 224 |
+
if curr is None or prev is None or prev == 0:
|
| 225 |
+
return None
|
| 226 |
+
return ((curr - prev) / prev) * 100
|
| 227 |
+
|
| 228 |
+
|
| 229 |
+
def _short_address(address: Any) -> str:
|
| 230 |
+
if not isinstance(address, str) or len(address) < 12:
|
| 231 |
+
return str(address)
|
| 232 |
+
return f"{address[:6]}...{address[-4:]}"
|
| 233 |
+
|
| 234 |
+
|
| 235 |
+
def _render_table(headers: List[tuple[str, str]], rows: List[Dict[str, Any]]) -> str:
|
| 236 |
+
if not rows:
|
| 237 |
+
return "(no data)"
|
| 238 |
+
|
| 239 |
+
prepared_rows: List[List[str]] = []
|
| 240 |
+
widths = [len(label) for label, _ in headers]
|
| 241 |
+
|
| 242 |
+
for row in rows:
|
| 243 |
+
rendered = []
|
| 244 |
+
for index, (_label, key) in enumerate(headers):
|
| 245 |
+
value = row.get(key, "")
|
| 246 |
+
text = str(value)
|
| 247 |
+
rendered.append(text)
|
| 248 |
+
if len(text) > widths[index]:
|
| 249 |
+
widths[index] = len(text)
|
| 250 |
+
prepared_rows.append(rendered)
|
| 251 |
+
|
| 252 |
+
lines = []
|
| 253 |
+
header_line = " ".join(label.ljust(widths[idx]) for idx, (label, _key) in enumerate(headers))
|
| 254 |
+
separator = " ".join("-" * widths[idx] for idx in range(len(headers)))
|
| 255 |
+
lines.extend([header_line, separator])
|
| 256 |
+
|
| 257 |
+
for rendered in prepared_rows:
|
| 258 |
+
lines.append(" ".join(rendered[idx].ljust(widths[idx]) for idx in range(len(rendered))))
|
| 259 |
+
return "\n".join(lines)
|
| 260 |
+
|
| 261 |
+
|
| 262 |
+
def _normalize_dexs(payload: Any) -> List[Dict[str, Any]]:
|
| 263 |
+
rows: List[Dict[str, Any]] = []
|
| 264 |
+
if not isinstance(payload, list):
|
| 265 |
+
return rows
|
| 266 |
+
|
| 267 |
+
for index, item in enumerate(payload):
|
| 268 |
+
if item is None:
|
| 269 |
+
rows.append(
|
| 270 |
+
{
|
| 271 |
+
"index": index,
|
| 272 |
+
"name": "",
|
| 273 |
+
"label": "first-perp-dex",
|
| 274 |
+
"full_name": "First perp dex",
|
| 275 |
+
"deployer": "-",
|
| 276 |
+
"asset_caps": 0,
|
| 277 |
+
}
|
| 278 |
+
)
|
| 279 |
+
continue
|
| 280 |
+
|
| 281 |
+
if not isinstance(item, dict):
|
| 282 |
+
continue
|
| 283 |
+
|
| 284 |
+
caps = item.get("assetToStreamingOiCap") or []
|
| 285 |
+
rows.append(
|
| 286 |
+
{
|
| 287 |
+
"index": index,
|
| 288 |
+
"name": item.get("name", ""),
|
| 289 |
+
"label": item.get("name") or "first-perp-dex",
|
| 290 |
+
"full_name": item.get("fullName") or "-",
|
| 291 |
+
"deployer": item.get("deployer") or "-",
|
| 292 |
+
"asset_caps": len(caps) if isinstance(caps, list) else 0,
|
| 293 |
+
}
|
| 294 |
+
)
|
| 295 |
+
return rows
|
| 296 |
+
|
| 297 |
+
|
| 298 |
+
def _normalize_perp_markets(payload: Any) -> List[Dict[str, Any]]:
|
| 299 |
+
if not isinstance(payload, list) or len(payload) < 2:
|
| 300 |
+
return []
|
| 301 |
+
|
| 302 |
+
meta = payload[0] if isinstance(payload[0], dict) else {}
|
| 303 |
+
ctxs = payload[1] if isinstance(payload[1], list) else []
|
| 304 |
+
universe = meta.get("universe") if isinstance(meta, dict) else []
|
| 305 |
+
if not isinstance(universe, list):
|
| 306 |
+
return []
|
| 307 |
+
|
| 308 |
+
rows: List[Dict[str, Any]] = []
|
| 309 |
+
for index, spec in enumerate(universe):
|
| 310 |
+
if not isinstance(spec, dict):
|
| 311 |
+
continue
|
| 312 |
+
ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {}
|
| 313 |
+
mark_px = ctx.get("markPx") or ctx.get("midPx") or ctx.get("oraclePx")
|
| 314 |
+
row = {
|
| 315 |
+
"coin": spec.get("name", f"asset-{index}"),
|
| 316 |
+
"mark_px": mark_px,
|
| 317 |
+
"mid_px": ctx.get("midPx"),
|
| 318 |
+
"oracle_px": ctx.get("oraclePx"),
|
| 319 |
+
"prev_day_px": ctx.get("prevDayPx"),
|
| 320 |
+
"change_pct": _percent_change(mark_px, ctx.get("prevDayPx")),
|
| 321 |
+
"funding": ctx.get("funding"),
|
| 322 |
+
"premium": ctx.get("premium"),
|
| 323 |
+
"open_interest": ctx.get("openInterest"),
|
| 324 |
+
"day_ntl_vlm": ctx.get("dayNtlVlm"),
|
| 325 |
+
"day_base_vlm": ctx.get("dayBaseVlm"),
|
| 326 |
+
"max_leverage": spec.get("maxLeverage"),
|
| 327 |
+
"sz_decimals": spec.get("szDecimals"),
|
| 328 |
+
"is_delisted": bool(spec.get("isDelisted")),
|
| 329 |
+
"only_isolated": bool(spec.get("onlyIsolated")),
|
| 330 |
+
"margin_mode": spec.get("marginMode") or "-",
|
| 331 |
+
}
|
| 332 |
+
rows.append(row)
|
| 333 |
+
return rows
|
| 334 |
+
|
| 335 |
+
|
| 336 |
+
def _normalize_spot_markets(payload: Any) -> List[Dict[str, Any]]:
|
| 337 |
+
if not isinstance(payload, list) or len(payload) < 2:
|
| 338 |
+
return []
|
| 339 |
+
|
| 340 |
+
meta = payload[0] if isinstance(payload[0], dict) else {}
|
| 341 |
+
ctxs = payload[1] if isinstance(payload[1], list) else []
|
| 342 |
+
pairs = meta.get("universe") if isinstance(meta, dict) else []
|
| 343 |
+
tokens = meta.get("tokens") if isinstance(meta, dict) else []
|
| 344 |
+
token_lookup = {}
|
| 345 |
+
if isinstance(tokens, list):
|
| 346 |
+
for token in tokens:
|
| 347 |
+
if isinstance(token, dict) and "index" in token:
|
| 348 |
+
token_lookup[token["index"]] = token.get("name", str(token["index"]))
|
| 349 |
+
|
| 350 |
+
rows: List[Dict[str, Any]] = []
|
| 351 |
+
if not isinstance(pairs, list):
|
| 352 |
+
return rows
|
| 353 |
+
|
| 354 |
+
for index, pair in enumerate(pairs):
|
| 355 |
+
if not isinstance(pair, dict):
|
| 356 |
+
continue
|
| 357 |
+
ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {}
|
| 358 |
+
raw_name = pair.get("name", f"@{index}")
|
| 359 |
+
tokens_for_pair = pair.get("tokens") if isinstance(pair.get("tokens"), list) else []
|
| 360 |
+
display_name = raw_name
|
| 361 |
+
if "/" not in raw_name and len(tokens_for_pair) == 2:
|
| 362 |
+
base = token_lookup.get(tokens_for_pair[0], str(tokens_for_pair[0]))
|
| 363 |
+
quote = token_lookup.get(tokens_for_pair[1], str(tokens_for_pair[1]))
|
| 364 |
+
display_name = f"{base}/{quote} ({raw_name})"
|
| 365 |
+
|
| 366 |
+
mark_px = ctx.get("markPx") or ctx.get("midPx")
|
| 367 |
+
rows.append(
|
| 368 |
+
{
|
| 369 |
+
"pair": raw_name,
|
| 370 |
+
"display_name": display_name,
|
| 371 |
+
"mark_px": mark_px,
|
| 372 |
+
"mid_px": ctx.get("midPx"),
|
| 373 |
+
"prev_day_px": ctx.get("prevDayPx"),
|
| 374 |
+
"change_pct": _percent_change(mark_px, ctx.get("prevDayPx")),
|
| 375 |
+
"day_ntl_vlm": ctx.get("dayNtlVlm"),
|
| 376 |
+
}
|
| 377 |
+
)
|
| 378 |
+
return rows
|
| 379 |
+
|
| 380 |
+
|
| 381 |
+
def _normalize_candles(payload: Any) -> List[Dict[str, Any]]:
|
| 382 |
+
rows: List[Dict[str, Any]] = []
|
| 383 |
+
if not isinstance(payload, list):
|
| 384 |
+
return rows
|
| 385 |
+
|
| 386 |
+
for candle in payload:
|
| 387 |
+
if not isinstance(candle, dict):
|
| 388 |
+
continue
|
| 389 |
+
rows.append(
|
| 390 |
+
{
|
| 391 |
+
"time": candle.get("t") or candle.get("time"),
|
| 392 |
+
"open": candle.get("o"),
|
| 393 |
+
"high": candle.get("h"),
|
| 394 |
+
"low": candle.get("l"),
|
| 395 |
+
"close": candle.get("c"),
|
| 396 |
+
"volume": candle.get("v"),
|
| 397 |
+
"trades": candle.get("n"),
|
| 398 |
+
}
|
| 399 |
+
)
|
| 400 |
+
|
| 401 |
+
rows.sort(key=lambda item: int(item.get("time") or 0))
|
| 402 |
+
return rows
|
| 403 |
+
|
| 404 |
+
|
| 405 |
+
def _normalize_funding_history(payload: Any) -> List[Dict[str, Any]]:
|
| 406 |
+
rows: List[Dict[str, Any]] = []
|
| 407 |
+
if not isinstance(payload, list):
|
| 408 |
+
return rows
|
| 409 |
+
|
| 410 |
+
for item in payload:
|
| 411 |
+
if not isinstance(item, dict):
|
| 412 |
+
continue
|
| 413 |
+
rows.append(
|
| 414 |
+
{
|
| 415 |
+
"coin": item.get("coin", "-"),
|
| 416 |
+
"funding_rate": item.get("fundingRate"),
|
| 417 |
+
"premium": item.get("premium"),
|
| 418 |
+
"time": item.get("time"),
|
| 419 |
+
}
|
| 420 |
+
)
|
| 421 |
+
|
| 422 |
+
rows.sort(key=lambda item: int(item.get("time") or 0))
|
| 423 |
+
return rows
|
| 424 |
+
|
| 425 |
+
|
| 426 |
+
def _normalize_book_levels(payload: Any) -> Dict[str, List[Dict[str, Any]]]:
|
| 427 |
+
if not isinstance(payload, dict):
|
| 428 |
+
return {"bids": [], "asks": []}
|
| 429 |
+
|
| 430 |
+
levels = payload.get("levels")
|
| 431 |
+
if not isinstance(levels, list) or len(levels) < 2:
|
| 432 |
+
return {"bids": [], "asks": []}
|
| 433 |
+
|
| 434 |
+
def convert(side: Iterable[Any]) -> List[Dict[str, Any]]:
|
| 435 |
+
converted = []
|
| 436 |
+
for entry in side:
|
| 437 |
+
if isinstance(entry, dict):
|
| 438 |
+
converted.append(
|
| 439 |
+
{
|
| 440 |
+
"px": entry.get("px"),
|
| 441 |
+
"sz": entry.get("sz"),
|
| 442 |
+
"orders": entry.get("n"),
|
| 443 |
+
}
|
| 444 |
+
)
|
| 445 |
+
elif isinstance(entry, (list, tuple)) and len(entry) >= 2:
|
| 446 |
+
converted.append(
|
| 447 |
+
{
|
| 448 |
+
"px": entry[0],
|
| 449 |
+
"sz": entry[1],
|
| 450 |
+
"orders": entry[2] if len(entry) > 2 else None,
|
| 451 |
+
}
|
| 452 |
+
)
|
| 453 |
+
return converted
|
| 454 |
+
|
| 455 |
+
return {"bids": convert(levels[0]), "asks": convert(levels[1])}
|
| 456 |
+
|
| 457 |
+
|
| 458 |
+
def _normalize_positions(payload: Any) -> Dict[str, Any]:
|
| 459 |
+
if not isinstance(payload, dict):
|
| 460 |
+
return {"summary": {}, "positions": []}
|
| 461 |
+
|
| 462 |
+
positions: List[Dict[str, Any]] = []
|
| 463 |
+
for item in payload.get("assetPositions", []):
|
| 464 |
+
if not isinstance(item, dict):
|
| 465 |
+
continue
|
| 466 |
+
position = item.get("position") if isinstance(item.get("position"), dict) else item
|
| 467 |
+
if not isinstance(position, dict):
|
| 468 |
+
continue
|
| 469 |
+
leverage = position.get("leverage") if isinstance(position.get("leverage"), dict) else {}
|
| 470 |
+
positions.append(
|
| 471 |
+
{
|
| 472 |
+
"coin": position.get("coin", "-"),
|
| 473 |
+
"size": position.get("szi"),
|
| 474 |
+
"entry_px": position.get("entryPx"),
|
| 475 |
+
"position_value": position.get("positionValue"),
|
| 476 |
+
"unrealized_pnl": position.get("unrealizedPnl"),
|
| 477 |
+
"return_on_equity": position.get("returnOnEquity"),
|
| 478 |
+
"liquidation_px": position.get("liquidationPx"),
|
| 479 |
+
"margin_used": position.get("marginUsed"),
|
| 480 |
+
"leverage": leverage.get("value"),
|
| 481 |
+
"leverage_type": leverage.get("type"),
|
| 482 |
+
}
|
| 483 |
+
)
|
| 484 |
+
|
| 485 |
+
positions.sort(
|
| 486 |
+
key=lambda item: abs(_safe_float(item.get("position_value")) or 0.0),
|
| 487 |
+
reverse=True,
|
| 488 |
+
)
|
| 489 |
+
|
| 490 |
+
summary = payload.get("marginSummary") if isinstance(payload.get("marginSummary"), dict) else {}
|
| 491 |
+
cross_summary = (
|
| 492 |
+
payload.get("crossMarginSummary") if isinstance(payload.get("crossMarginSummary"), dict) else {}
|
| 493 |
+
)
|
| 494 |
+
|
| 495 |
+
return {
|
| 496 |
+
"summary": {
|
| 497 |
+
"account_value": summary.get("accountValue"),
|
| 498 |
+
"total_ntl_pos": summary.get("totalNtlPos"),
|
| 499 |
+
"total_raw_usd": summary.get("totalRawUsd"),
|
| 500 |
+
"withdrawable": payload.get("withdrawable"),
|
| 501 |
+
"cross_account_value": cross_summary.get("accountValue"),
|
| 502 |
+
},
|
| 503 |
+
"positions": positions,
|
| 504 |
+
}
|
| 505 |
+
|
| 506 |
+
|
| 507 |
+
def _normalize_spot_balances(payload: Any) -> List[Dict[str, Any]]:
|
| 508 |
+
if not isinstance(payload, dict):
|
| 509 |
+
return []
|
| 510 |
+
|
| 511 |
+
rows: List[Dict[str, Any]] = []
|
| 512 |
+
for item in payload.get("balances", []):
|
| 513 |
+
if not isinstance(item, dict):
|
| 514 |
+
continue
|
| 515 |
+
rows.append(
|
| 516 |
+
{
|
| 517 |
+
"coin": item.get("coin", item.get("token", "-")),
|
| 518 |
+
"total": item.get("total"),
|
| 519 |
+
"hold": item.get("hold"),
|
| 520 |
+
"entry_ntl": item.get("entryNtl"),
|
| 521 |
+
}
|
| 522 |
+
)
|
| 523 |
+
|
| 524 |
+
rows.sort(key=lambda item: abs(_safe_float(item.get("entry_ntl")) or 0.0), reverse=True)
|
| 525 |
+
return rows
|
| 526 |
+
|
| 527 |
+
|
| 528 |
+
def _normalize_fills(payload: Any) -> List[Dict[str, Any]]:
|
| 529 |
+
rows: List[Dict[str, Any]] = []
|
| 530 |
+
if not isinstance(payload, list):
|
| 531 |
+
return rows
|
| 532 |
+
|
| 533 |
+
for item in payload:
|
| 534 |
+
if not isinstance(item, dict):
|
| 535 |
+
continue
|
| 536 |
+
fill = item.get("fill") if isinstance(item.get("fill"), dict) else item
|
| 537 |
+
rows.append(
|
| 538 |
+
{
|
| 539 |
+
"coin": fill.get("coin", "-"),
|
| 540 |
+
"dir": fill.get("dir") or fill.get("side") or "-",
|
| 541 |
+
"px": fill.get("px"),
|
| 542 |
+
"sz": fill.get("sz"),
|
| 543 |
+
"closed_pnl": fill.get("closedPnl"),
|
| 544 |
+
"fee": fill.get("fee"),
|
| 545 |
+
"fee_token": fill.get("feeToken"),
|
| 546 |
+
"start_position": fill.get("startPosition"),
|
| 547 |
+
"time": fill.get("time"),
|
| 548 |
+
"hash": fill.get("hash"),
|
| 549 |
+
"oid": fill.get("oid"),
|
| 550 |
+
"twap_id": item.get("twapId"),
|
| 551 |
+
}
|
| 552 |
+
)
|
| 553 |
+
|
| 554 |
+
rows.sort(key=lambda item: int(item.get("time") or 0), reverse=True)
|
| 555 |
+
return rows
|
| 556 |
+
|
| 557 |
+
|
| 558 |
+
def _normalize_orders(payload: Any) -> List[Dict[str, Any]]:
|
| 559 |
+
rows: List[Dict[str, Any]] = []
|
| 560 |
+
if not isinstance(payload, list):
|
| 561 |
+
return rows
|
| 562 |
+
|
| 563 |
+
for item in payload:
|
| 564 |
+
if not isinstance(item, dict):
|
| 565 |
+
continue
|
| 566 |
+
order = item.get("order") if isinstance(item.get("order"), dict) else item
|
| 567 |
+
rows.append(
|
| 568 |
+
{
|
| 569 |
+
"coin": order.get("coin", "-"),
|
| 570 |
+
"side": order.get("side", "-"),
|
| 571 |
+
"limit_px": order.get("limitPx") or order.get("px"),
|
| 572 |
+
"size": order.get("sz") or order.get("origSz"),
|
| 573 |
+
"timestamp": item.get("statusTimestamp")
|
| 574 |
+
or order.get("timestamp")
|
| 575 |
+
or order.get("time"),
|
| 576 |
+
"status": item.get("status") or order.get("status") or "-",
|
| 577 |
+
"oid": order.get("oid"),
|
| 578 |
+
"order_type": order.get("orderType") or "-",
|
| 579 |
+
}
|
| 580 |
+
)
|
| 581 |
+
|
| 582 |
+
rows.sort(key=lambda item: int(item.get("timestamp") or 0), reverse=True)
|
| 583 |
+
return rows
|
| 584 |
+
|
| 585 |
+
|
| 586 |
+
def _direction_bucket(direction: Any) -> str:
|
| 587 |
+
text = str(direction or "").strip().lower()
|
| 588 |
+
if "open" in text and "long" in text:
|
| 589 |
+
return "open_long"
|
| 590 |
+
if "close" in text and "long" in text:
|
| 591 |
+
return "close_long"
|
| 592 |
+
if "open" in text and "short" in text:
|
| 593 |
+
return "open_short"
|
| 594 |
+
if "close" in text and "short" in text:
|
| 595 |
+
return "close_short"
|
| 596 |
+
if text in {"b", "buy"}:
|
| 597 |
+
return "buy"
|
| 598 |
+
if text in {"s", "sell"}:
|
| 599 |
+
return "sell"
|
| 600 |
+
return "other"
|
| 601 |
+
|
| 602 |
+
|
| 603 |
+
def _average(values: Iterable[Optional[float]]) -> Optional[float]:
|
| 604 |
+
clean_values = [value for value in values if value is not None]
|
| 605 |
+
if not clean_values:
|
| 606 |
+
return None
|
| 607 |
+
return round(sum(clean_values) / len(clean_values), 12)
|
| 608 |
+
|
| 609 |
+
|
| 610 |
+
def _is_spot_coin(coin: str) -> bool:
|
| 611 |
+
return "/" in coin or coin.startswith("@")
|
| 612 |
+
|
| 613 |
+
|
| 614 |
+
def _safe_info_query(payload: Dict[str, Any]) -> Any:
|
| 615 |
+
try:
|
| 616 |
+
return _post_info(payload)
|
| 617 |
+
except SystemExit:
|
| 618 |
+
return None
|
| 619 |
+
|
| 620 |
+
|
| 621 |
+
def _market_context_for_coin(coin: str, interval: str, start_ms: int, end_ms: int) -> Dict[str, Any]:
|
| 622 |
+
candles = _normalize_candles(
|
| 623 |
+
_safe_info_query(
|
| 624 |
+
{
|
| 625 |
+
"type": "candleSnapshot",
|
| 626 |
+
"req": {
|
| 627 |
+
"coin": coin,
|
| 628 |
+
"interval": interval,
|
| 629 |
+
"startTime": start_ms,
|
| 630 |
+
"endTime": end_ms,
|
| 631 |
+
},
|
| 632 |
+
}
|
| 633 |
+
)
|
| 634 |
+
)
|
| 635 |
+
funding_history: List[Dict[str, Any]] = []
|
| 636 |
+
if not _is_spot_coin(coin):
|
| 637 |
+
funding_history = _normalize_funding_history(
|
| 638 |
+
_safe_info_query(
|
| 639 |
+
{
|
| 640 |
+
"type": "fundingHistory",
|
| 641 |
+
"coin": coin,
|
| 642 |
+
"startTime": start_ms,
|
| 643 |
+
"endTime": end_ms,
|
| 644 |
+
}
|
| 645 |
+
)
|
| 646 |
+
)
|
| 647 |
+
|
| 648 |
+
candle_change = None
|
| 649 |
+
if candles:
|
| 650 |
+
candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open"))
|
| 651 |
+
|
| 652 |
+
funding_average = _average(_safe_float(item.get("funding_rate")) for item in funding_history)
|
| 653 |
+
return {
|
| 654 |
+
"coin": coin,
|
| 655 |
+
"interval": interval,
|
| 656 |
+
"candle_count": len(candles),
|
| 657 |
+
"price_change_pct": candle_change,
|
| 658 |
+
"window_open": candles[0].get("open") if candles else None,
|
| 659 |
+
"window_close": candles[-1].get("close") if candles else None,
|
| 660 |
+
"average_funding_rate": funding_average,
|
| 661 |
+
"funding_samples": len(funding_history),
|
| 662 |
+
}
|
| 663 |
+
|
| 664 |
+
|
| 665 |
+
def _build_coin_review(coin: str, fills: List[Dict[str, Any]], interval: str, start_ms: int, end_ms: int) -> Dict[str, Any]:
|
| 666 |
+
pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills]
|
| 667 |
+
fee_values = [_safe_float(fill.get("fee")) for fill in fills]
|
| 668 |
+
scored = [value for value in pnl_values if value is not None]
|
| 669 |
+
wins = [value for value in scored if value > 0]
|
| 670 |
+
losses = [value for value in scored if value < 0]
|
| 671 |
+
breakeven = [value for value in scored if value == 0]
|
| 672 |
+
|
| 673 |
+
direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills)
|
| 674 |
+
market_context = _market_context_for_coin(coin, interval, start_ms, end_ms)
|
| 675 |
+
total_pnl = sum(value for value in pnl_values if value is not None)
|
| 676 |
+
total_fees = sum(value for value in fee_values if value is not None)
|
| 677 |
+
net_after_fees = total_pnl - total_fees
|
| 678 |
+
|
| 679 |
+
if direction_counts["open_long"] > direction_counts["open_short"]:
|
| 680 |
+
open_bias = "long"
|
| 681 |
+
elif direction_counts["open_short"] > direction_counts["open_long"]:
|
| 682 |
+
open_bias = "short"
|
| 683 |
+
elif direction_counts["open_long"] or direction_counts["open_short"]:
|
| 684 |
+
open_bias = "mixed"
|
| 685 |
+
else:
|
| 686 |
+
open_bias = "none"
|
| 687 |
+
|
| 688 |
+
return {
|
| 689 |
+
"coin": coin,
|
| 690 |
+
"fill_count": len(fills),
|
| 691 |
+
"realized_pnl": total_pnl,
|
| 692 |
+
"total_fees": total_fees,
|
| 693 |
+
"net_after_fees": net_after_fees,
|
| 694 |
+
"wins": len(wins),
|
| 695 |
+
"losses": len(losses),
|
| 696 |
+
"breakeven": len(breakeven),
|
| 697 |
+
"win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None,
|
| 698 |
+
"open_long_count": direction_counts["open_long"],
|
| 699 |
+
"open_short_count": direction_counts["open_short"],
|
| 700 |
+
"close_long_count": direction_counts["close_long"],
|
| 701 |
+
"close_short_count": direction_counts["close_short"],
|
| 702 |
+
"open_bias": open_bias,
|
| 703 |
+
"market_context": market_context,
|
| 704 |
+
}
|
| 705 |
+
|
| 706 |
+
|
| 707 |
+
def _review_findings(summary: Dict[str, Any], coin_reviews: List[Dict[str, Any]]) -> List[str]:
|
| 708 |
+
findings: List[str] = []
|
| 709 |
+
|
| 710 |
+
if summary["fill_count"] == 0:
|
| 711 |
+
return ["No fills were found in the requested review window."]
|
| 712 |
+
|
| 713 |
+
if summary["outcome_fill_count"] == 0:
|
| 714 |
+
findings.append("Most fills in this window look like opens or adjustments, so realized-outcome review is limited until positions close.")
|
| 715 |
+
|
| 716 |
+
if summary["net_after_fees"] < 0:
|
| 717 |
+
findings.append(
|
| 718 |
+
f"Net realized PnL after fees was negative ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)."
|
| 719 |
+
)
|
| 720 |
+
elif summary["net_after_fees"] > 0:
|
| 721 |
+
findings.append(
|
| 722 |
+
f"Net realized PnL after fees was positive ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)."
|
| 723 |
+
)
|
| 724 |
+
|
| 725 |
+
realized_abs = abs(summary["realized_pnl"])
|
| 726 |
+
if summary["total_fees"] > 0:
|
| 727 |
+
if realized_abs == 0:
|
| 728 |
+
findings.append("Fees were non-trivial while realized PnL stayed flat, which usually means churn without enough edge.")
|
| 729 |
+
elif summary["total_fees"] / realized_abs >= 0.25:
|
| 730 |
+
ratio_pct = (summary["total_fees"] / realized_abs) * 100
|
| 731 |
+
findings.append(f"Fees consumed about {ratio_pct:.1f}% of absolute realized PnL, so execution efficiency is materially affecting results.")
|
| 732 |
+
|
| 733 |
+
if summary["fill_count"] >= 20 and summary["net_after_fees"] < 0:
|
| 734 |
+
win_rate = summary.get("win_rate_pct")
|
| 735 |
+
if win_rate is None or win_rate < 45:
|
| 736 |
+
findings.append("Activity was high relative to results, which suggests overtrading in this review window.")
|
| 737 |
+
|
| 738 |
+
if coin_reviews:
|
| 739 |
+
worst_coin = min(coin_reviews, key=lambda item: item["net_after_fees"])
|
| 740 |
+
best_coin = max(coin_reviews, key=lambda item: item["net_after_fees"])
|
| 741 |
+
if worst_coin["net_after_fees"] < 0:
|
| 742 |
+
findings.append(
|
| 743 |
+
f"The weakest coin was {worst_coin['coin']} with net after fees of {_compact_number(worst_coin['net_after_fees'])}."
|
| 744 |
+
)
|
| 745 |
+
if best_coin["net_after_fees"] > 0 and best_coin["coin"] != worst_coin["coin"]:
|
| 746 |
+
findings.append(
|
| 747 |
+
f"The strongest coin was {best_coin['coin']} with net after fees of {_compact_number(best_coin['net_after_fees'])}."
|
| 748 |
+
)
|
| 749 |
+
|
| 750 |
+
for item in coin_reviews:
|
| 751 |
+
market_change = item["market_context"].get("price_change_pct")
|
| 752 |
+
if item["net_after_fees"] >= 0 or market_change is None:
|
| 753 |
+
continue
|
| 754 |
+
if market_change > 2 and item["open_short_count"] > item["open_long_count"]:
|
| 755 |
+
findings.append(f"{item['coin']}: losses came while leaning short into a rising market window.")
|
| 756 |
+
elif market_change < -2 and item["open_long_count"] > item["open_short_count"]:
|
| 757 |
+
findings.append(f"{item['coin']}: losses came while leaning long into a falling market window.")
|
| 758 |
+
|
| 759 |
+
deduped: List[str] = []
|
| 760 |
+
for finding in findings:
|
| 761 |
+
if finding not in deduped:
|
| 762 |
+
deduped.append(finding)
|
| 763 |
+
return deduped[:6]
|
| 764 |
+
|
| 765 |
+
|
| 766 |
+
def _recent_fill_rows(fills: List[Dict[str, Any]], limit: int) -> List[Dict[str, Any]]:
|
| 767 |
+
rows = []
|
| 768 |
+
for fill in _limit_items(fills, limit):
|
| 769 |
+
rows.append(
|
| 770 |
+
{
|
| 771 |
+
"time": fill.get("time"),
|
| 772 |
+
"coin": fill.get("coin"),
|
| 773 |
+
"dir": fill.get("dir"),
|
| 774 |
+
"px": fill.get("px"),
|
| 775 |
+
"sz": fill.get("sz"),
|
| 776 |
+
"closed_pnl": fill.get("closed_pnl"),
|
| 777 |
+
"fee": fill.get("fee"),
|
| 778 |
+
"fee_token": fill.get("fee_token"),
|
| 779 |
+
}
|
| 780 |
+
)
|
| 781 |
+
return rows
|
| 782 |
+
|
| 783 |
+
|
| 784 |
+
def _coin_slug(coin: str) -> str:
|
| 785 |
+
slug = str(coin or "market").strip().lower()
|
| 786 |
+
for old, new in (("/", "-"), (":", "-"), ("@", "spot-"), (" ", "-")):
|
| 787 |
+
slug = slug.replace(old, new)
|
| 788 |
+
return slug or "market"
|
| 789 |
+
|
| 790 |
+
|
| 791 |
+
def _default_export_path(coin: str, interval: str, hours: float) -> Path:
|
| 792 |
+
hour_label = str(int(hours)) if float(hours).is_integer() else str(hours).replace(".", "p")
|
| 793 |
+
filename = f"hyperliquid-{_coin_slug(coin)}-{interval}-{hour_label}h.json"
|
| 794 |
+
return Path.cwd() / filename
|
| 795 |
+
|
| 796 |
+
|
| 797 |
+
def _write_json_file(path: Path, payload: Dict[str, Any]) -> None:
|
| 798 |
+
path.parent.mkdir(parents=True, exist_ok=True)
|
| 799 |
+
path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
|
| 800 |
+
|
| 801 |
+
|
| 802 |
+
def _export_summary(candles: List[Dict[str, Any]], funding_history: List[Dict[str, Any]]) -> Dict[str, Any]:
|
| 803 |
+
candle_change = None
|
| 804 |
+
if candles:
|
| 805 |
+
candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open"))
|
| 806 |
+
return {
|
| 807 |
+
"candle_count": len(candles),
|
| 808 |
+
"funding_count": len(funding_history),
|
| 809 |
+
"window_open": candles[0].get("open") if candles else None,
|
| 810 |
+
"window_close": candles[-1].get("close") if candles else None,
|
| 811 |
+
"price_change_pct": candle_change,
|
| 812 |
+
"average_funding_rate": _average(_safe_float(item.get("funding_rate")) for item in funding_history),
|
| 813 |
+
}
|
| 814 |
+
|
| 815 |
+
|
| 816 |
+
def run_dexs(_args: argparse.Namespace) -> Dict[str, Any]:
|
| 817 |
+
payload = _post_info({"type": "perpDexs"})
|
| 818 |
+
rows = _normalize_dexs(payload)
|
| 819 |
+
return {"api_url": _info_url(), "count": len(rows), "dexs": rows}
|
| 820 |
+
|
| 821 |
+
|
| 822 |
+
def run_markets(args: argparse.Namespace) -> Dict[str, Any]:
|
| 823 |
+
payload: Dict[str, Any] = {"type": "metaAndAssetCtxs"}
|
| 824 |
+
if args.dex:
|
| 825 |
+
payload["dex"] = args.dex
|
| 826 |
+
rows = _normalize_perp_markets(_post_info(payload))
|
| 827 |
+
|
| 828 |
+
if args.sort == "name":
|
| 829 |
+
rows.sort(key=lambda item: item["coin"])
|
| 830 |
+
elif args.sort == "oi":
|
| 831 |
+
rows.sort(key=lambda item: _safe_float(item.get("open_interest")) or 0.0, reverse=True)
|
| 832 |
+
elif args.sort == "funding_abs":
|
| 833 |
+
rows.sort(key=lambda item: abs(_safe_float(item.get("funding")) or 0.0), reverse=True)
|
| 834 |
+
elif args.sort == "change_abs":
|
| 835 |
+
rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True)
|
| 836 |
+
else:
|
| 837 |
+
rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True)
|
| 838 |
+
|
| 839 |
+
return {
|
| 840 |
+
"dex": args.dex or "",
|
| 841 |
+
"count": len(rows),
|
| 842 |
+
"sort": args.sort,
|
| 843 |
+
"markets": _limit_items(rows, args.limit),
|
| 844 |
+
}
|
| 845 |
+
|
| 846 |
+
|
| 847 |
+
def run_spots(args: argparse.Namespace) -> Dict[str, Any]:
|
| 848 |
+
rows = _normalize_spot_markets(_post_info({"type": "spotMetaAndAssetCtxs"}))
|
| 849 |
+
|
| 850 |
+
if args.sort == "name":
|
| 851 |
+
rows.sort(key=lambda item: item["display_name"])
|
| 852 |
+
elif args.sort == "change_abs":
|
| 853 |
+
rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True)
|
| 854 |
+
else:
|
| 855 |
+
rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True)
|
| 856 |
+
|
| 857 |
+
return {"count": len(rows), "sort": args.sort, "pairs": _limit_items(rows, args.limit)}
|
| 858 |
+
|
| 859 |
+
|
| 860 |
+
def run_candles(args: argparse.Namespace) -> Dict[str, Any]:
|
| 861 |
+
end_ms = int(time.time() * 1000)
|
| 862 |
+
start_ms = _hours_ago_ms(args.hours, end_ms)
|
| 863 |
+
payload = {
|
| 864 |
+
"type": "candleSnapshot",
|
| 865 |
+
"req": {
|
| 866 |
+
"coin": args.coin,
|
| 867 |
+
"interval": args.interval,
|
| 868 |
+
"startTime": start_ms,
|
| 869 |
+
"endTime": end_ms,
|
| 870 |
+
},
|
| 871 |
+
}
|
| 872 |
+
candles = _normalize_candles(_post_info(payload))
|
| 873 |
+
summary = {}
|
| 874 |
+
if candles:
|
| 875 |
+
highs = [_safe_float(item.get("high")) for item in candles]
|
| 876 |
+
lows = [_safe_float(item.get("low")) for item in candles]
|
| 877 |
+
clean_highs = [value for value in highs if value is not None]
|
| 878 |
+
clean_lows = [value for value in lows if value is not None]
|
| 879 |
+
summary = {
|
| 880 |
+
"first_time": candles[0]["time"],
|
| 881 |
+
"last_time": candles[-1]["time"],
|
| 882 |
+
"open": candles[0]["open"],
|
| 883 |
+
"close": candles[-1]["close"],
|
| 884 |
+
"high": max(clean_highs) if clean_highs else None,
|
| 885 |
+
"low": min(clean_lows) if clean_lows else None,
|
| 886 |
+
"change_pct": _percent_change(candles[-1]["close"], candles[0]["open"]),
|
| 887 |
+
}
|
| 888 |
+
return {
|
| 889 |
+
"coin": args.coin,
|
| 890 |
+
"interval": args.interval,
|
| 891 |
+
"hours": args.hours,
|
| 892 |
+
"count": len(candles),
|
| 893 |
+
"summary": summary,
|
| 894 |
+
"candles": _limit_items(candles, args.limit),
|
| 895 |
+
}
|
| 896 |
+
|
| 897 |
+
|
| 898 |
+
def run_funding(args: argparse.Namespace) -> Dict[str, Any]:
|
| 899 |
+
end_ms = int(time.time() * 1000)
|
| 900 |
+
start_ms = _hours_ago_ms(args.hours, end_ms)
|
| 901 |
+
payload = {"type": "fundingHistory", "coin": args.coin, "startTime": start_ms, "endTime": end_ms}
|
| 902 |
+
rows = _normalize_funding_history(_post_info(payload))
|
| 903 |
+
avg_rate = None
|
| 904 |
+
if rows:
|
| 905 |
+
values = [_safe_float(item.get("funding_rate")) for item in rows]
|
| 906 |
+
clean_values = [value for value in values if value is not None]
|
| 907 |
+
if clean_values:
|
| 908 |
+
avg_rate = sum(clean_values) / len(clean_values)
|
| 909 |
+
return {
|
| 910 |
+
"coin": args.coin,
|
| 911 |
+
"hours": args.hours,
|
| 912 |
+
"count": len(rows),
|
| 913 |
+
"average_funding_rate": avg_rate,
|
| 914 |
+
"history": _limit_items(list(reversed(rows)), args.limit),
|
| 915 |
+
}
|
| 916 |
+
|
| 917 |
+
|
| 918 |
+
def run_l2(args: argparse.Namespace) -> Dict[str, Any]:
|
| 919 |
+
payload: Dict[str, Any] = {"type": "l2Book", "coin": args.coin}
|
| 920 |
+
if args.n_sig_figs is not None:
|
| 921 |
+
payload["nSigFigs"] = args.n_sig_figs
|
| 922 |
+
if args.mantissa is not None:
|
| 923 |
+
payload["mantissa"] = args.mantissa
|
| 924 |
+
raw = _post_info(payload)
|
| 925 |
+
levels = _normalize_book_levels(raw)
|
| 926 |
+
return {
|
| 927 |
+
"coin": args.coin,
|
| 928 |
+
"time": raw.get("time") if isinstance(raw, dict) else None,
|
| 929 |
+
"bids": _limit_items(levels["bids"], args.levels),
|
| 930 |
+
"asks": _limit_items(levels["asks"], args.levels),
|
| 931 |
+
}
|
| 932 |
+
|
| 933 |
+
|
| 934 |
+
def run_state(args: argparse.Namespace) -> Dict[str, Any]:
|
| 935 |
+
user = _resolve_user(args.user)
|
| 936 |
+
payload: Dict[str, Any] = {"type": "clearinghouseState", "user": user}
|
| 937 |
+
if args.dex:
|
| 938 |
+
payload["dex"] = args.dex
|
| 939 |
+
normalized = _normalize_positions(_post_info(payload))
|
| 940 |
+
return {
|
| 941 |
+
"user": user,
|
| 942 |
+
"dex": args.dex or "",
|
| 943 |
+
"summary": normalized["summary"],
|
| 944 |
+
"positions": normalized["positions"],
|
| 945 |
+
}
|
| 946 |
+
|
| 947 |
+
|
| 948 |
+
def run_spot_balances(args: argparse.Namespace) -> Dict[str, Any]:
|
| 949 |
+
user = _resolve_user(args.user)
|
| 950 |
+
payload = {"type": "spotClearinghouseState", "user": user}
|
| 951 |
+
rows = _normalize_spot_balances(_post_info(payload))
|
| 952 |
+
return {"user": user, "count": len(rows), "balances": _limit_items(rows, args.limit)}
|
| 953 |
+
|
| 954 |
+
|
| 955 |
+
def run_fills(args: argparse.Namespace) -> Dict[str, Any]:
|
| 956 |
+
user = _resolve_user(args.user)
|
| 957 |
+
payload: Dict[str, Any] = {"user": user}
|
| 958 |
+
if args.hours is not None:
|
| 959 |
+
payload["type"] = "userFillsByTime"
|
| 960 |
+
payload["startTime"] = _hours_ago_ms(args.hours)
|
| 961 |
+
else:
|
| 962 |
+
payload["type"] = "userFills"
|
| 963 |
+
if args.aggregate_by_time:
|
| 964 |
+
payload["aggregateByTime"] = True
|
| 965 |
+
rows = _normalize_fills(_post_info(payload))
|
| 966 |
+
return {
|
| 967 |
+
"user": user,
|
| 968 |
+
"hours": args.hours,
|
| 969 |
+
"aggregate_by_time": args.aggregate_by_time,
|
| 970 |
+
"count": len(rows),
|
| 971 |
+
"fills": _limit_items(rows, args.limit),
|
| 972 |
+
}
|
| 973 |
+
|
| 974 |
+
|
| 975 |
+
def run_orders(args: argparse.Namespace) -> Dict[str, Any]:
|
| 976 |
+
user = _resolve_user(args.user)
|
| 977 |
+
payload = {"type": "historicalOrders", "user": user}
|
| 978 |
+
rows = _normalize_orders(_post_info(payload))
|
| 979 |
+
return {"user": user, "count": len(rows), "orders": _limit_items(rows, args.limit)}
|
| 980 |
+
|
| 981 |
+
|
| 982 |
+
def run_review(args: argparse.Namespace) -> Dict[str, Any]:
|
| 983 |
+
user = _resolve_user(args.user)
|
| 984 |
+
end_ms = int(time.time() * 1000)
|
| 985 |
+
start_ms = _hours_ago_ms(args.hours, end_ms)
|
| 986 |
+
payload: Dict[str, Any] = {"type": "userFillsByTime", "user": user, "startTime": start_ms}
|
| 987 |
+
if args.aggregate_by_time:
|
| 988 |
+
payload["aggregateByTime"] = True
|
| 989 |
+
|
| 990 |
+
fills = _normalize_fills(_post_info(payload))
|
| 991 |
+
if args.coin:
|
| 992 |
+
target = args.coin.lower()
|
| 993 |
+
fills = [fill for fill in fills if str(fill.get("coin", "")).lower() == target]
|
| 994 |
+
fills = _limit_items(fills, args.fills)
|
| 995 |
+
|
| 996 |
+
grouped: Dict[str, List[Dict[str, Any]]] = {}
|
| 997 |
+
for fill in fills:
|
| 998 |
+
grouped.setdefault(fill.get("coin", "-"), []).append(fill)
|
| 999 |
+
|
| 1000 |
+
coin_reviews = [
|
| 1001 |
+
_build_coin_review(coin, coin_fills, args.interval, start_ms, end_ms)
|
| 1002 |
+
for coin, coin_fills in sorted(grouped.items(), key=lambda item: len(item[1]), reverse=True)
|
| 1003 |
+
]
|
| 1004 |
+
|
| 1005 |
+
pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills]
|
| 1006 |
+
fee_values = [_safe_float(fill.get("fee")) for fill in fills]
|
| 1007 |
+
scored = [value for value in pnl_values if value is not None]
|
| 1008 |
+
wins = [value for value in scored if value > 0]
|
| 1009 |
+
losses = [value for value in scored if value < 0]
|
| 1010 |
+
direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills)
|
| 1011 |
+
total_pnl = sum(value for value in pnl_values if value is not None)
|
| 1012 |
+
total_fees = sum(value for value in fee_values if value is not None)
|
| 1013 |
+
|
| 1014 |
+
summary = {
|
| 1015 |
+
"fill_count": len(fills),
|
| 1016 |
+
"scored_fill_count": len(scored),
|
| 1017 |
+
"outcome_fill_count": len(wins) + len(losses),
|
| 1018 |
+
"unique_coins": len(grouped),
|
| 1019 |
+
"realized_pnl": total_pnl,
|
| 1020 |
+
"total_fees": total_fees,
|
| 1021 |
+
"net_after_fees": total_pnl - total_fees,
|
| 1022 |
+
"wins": len(wins),
|
| 1023 |
+
"losses": len(losses),
|
| 1024 |
+
"breakeven": len([value for value in scored if value == 0]),
|
| 1025 |
+
"win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None,
|
| 1026 |
+
"open_long_count": direction_counts["open_long"],
|
| 1027 |
+
"open_short_count": direction_counts["open_short"],
|
| 1028 |
+
"close_long_count": direction_counts["close_long"],
|
| 1029 |
+
"close_short_count": direction_counts["close_short"],
|
| 1030 |
+
}
|
| 1031 |
+
|
| 1032 |
+
return {
|
| 1033 |
+
"user": user,
|
| 1034 |
+
"coin_filter": args.coin,
|
| 1035 |
+
"hours": args.hours,
|
| 1036 |
+
"interval": args.interval,
|
| 1037 |
+
"fills_requested": args.fills,
|
| 1038 |
+
"summary": summary,
|
| 1039 |
+
"findings": _review_findings(summary, coin_reviews),
|
| 1040 |
+
"coin_reviews": coin_reviews,
|
| 1041 |
+
"recent_fills": _recent_fill_rows(fills, args.recent),
|
| 1042 |
+
}
|
| 1043 |
+
|
| 1044 |
+
|
| 1045 |
+
def run_export(args: argparse.Namespace) -> Dict[str, Any]:
|
| 1046 |
+
end_ms = args.end_time_ms if args.end_time_ms is not None else int(time.time() * 1000)
|
| 1047 |
+
start_ms = _hours_ago_ms(args.hours, end_ms)
|
| 1048 |
+
|
| 1049 |
+
candle_payload = {
|
| 1050 |
+
"type": "candleSnapshot",
|
| 1051 |
+
"req": {
|
| 1052 |
+
"coin": args.coin,
|
| 1053 |
+
"interval": args.interval,
|
| 1054 |
+
"startTime": start_ms,
|
| 1055 |
+
"endTime": end_ms,
|
| 1056 |
+
},
|
| 1057 |
+
}
|
| 1058 |
+
candles = _normalize_candles(_post_info(candle_payload))
|
| 1059 |
+
|
| 1060 |
+
funding_history: List[Dict[str, Any]] = []
|
| 1061 |
+
if not _is_spot_coin(args.coin):
|
| 1062 |
+
funding_history = _normalize_funding_history(
|
| 1063 |
+
_safe_info_query(
|
| 1064 |
+
{
|
| 1065 |
+
"type": "fundingHistory",
|
| 1066 |
+
"coin": args.coin,
|
| 1067 |
+
"startTime": start_ms,
|
| 1068 |
+
"endTime": end_ms,
|
| 1069 |
+
}
|
| 1070 |
+
)
|
| 1071 |
+
)
|
| 1072 |
+
|
| 1073 |
+
output_path = Path(args.output) if args.output else _default_export_path(args.coin, args.interval, args.hours)
|
| 1074 |
+
payload = {
|
| 1075 |
+
"schema_version": "hyperliquid-market-export-v1",
|
| 1076 |
+
"source": {
|
| 1077 |
+
"api_url": _info_url(),
|
| 1078 |
+
"interval": args.interval,
|
| 1079 |
+
"coin": args.coin,
|
| 1080 |
+
"market_type": "spot" if _is_spot_coin(args.coin) else "perp",
|
| 1081 |
+
},
|
| 1082 |
+
"window": {
|
| 1083 |
+
"start_time_ms": start_ms,
|
| 1084 |
+
"end_time_ms": end_ms,
|
| 1085 |
+
"hours": args.hours,
|
| 1086 |
+
},
|
| 1087 |
+
"summary": _export_summary(candles, funding_history),
|
| 1088 |
+
"candles": candles,
|
| 1089 |
+
"funding_history": funding_history,
|
| 1090 |
+
}
|
| 1091 |
+
_write_json_file(output_path, payload)
|
| 1092 |
+
return {
|
| 1093 |
+
"coin": args.coin,
|
| 1094 |
+
"interval": args.interval,
|
| 1095 |
+
"hours": args.hours,
|
| 1096 |
+
"output_path": str(output_path),
|
| 1097 |
+
"summary": payload["summary"],
|
| 1098 |
+
"schema_version": payload["schema_version"],
|
| 1099 |
+
}
|
| 1100 |
+
|
| 1101 |
+
|
| 1102 |
+
def render_dexs(data: Dict[str, Any]) -> str:
|
| 1103 |
+
rows = [
|
| 1104 |
+
{
|
| 1105 |
+
"label": item["label"],
|
| 1106 |
+
"full_name": item["full_name"],
|
| 1107 |
+
"deployer": _short_address(item["deployer"]),
|
| 1108 |
+
"asset_caps": item["asset_caps"],
|
| 1109 |
+
}
|
| 1110 |
+
for item in data["dexs"]
|
| 1111 |
+
]
|
| 1112 |
+
return "\n".join(
|
| 1113 |
+
[
|
| 1114 |
+
f"API: {data['api_url']}",
|
| 1115 |
+
f"Perp dexs: {data['count']}",
|
| 1116 |
+
"",
|
| 1117 |
+
_render_table(
|
| 1118 |
+
[
|
| 1119 |
+
("Dex", "label"),
|
| 1120 |
+
("Full Name", "full_name"),
|
| 1121 |
+
("Deployer", "deployer"),
|
| 1122 |
+
("Asset Caps", "asset_caps"),
|
| 1123 |
+
],
|
| 1124 |
+
rows,
|
| 1125 |
+
),
|
| 1126 |
+
]
|
| 1127 |
+
)
|
| 1128 |
+
|
| 1129 |
+
|
| 1130 |
+
def render_markets(data: Dict[str, Any]) -> str:
|
| 1131 |
+
rows = [
|
| 1132 |
+
{
|
| 1133 |
+
"coin": item["coin"],
|
| 1134 |
+
"mark_px": _format_price(item["mark_px"]),
|
| 1135 |
+
"change_pct": _format_percent(item["change_pct"]),
|
| 1136 |
+
"funding": _format_fraction_percent(item["funding"]),
|
| 1137 |
+
"open_interest": _compact_number(item["open_interest"]),
|
| 1138 |
+
"day_ntl_vlm": _compact_number(item["day_ntl_vlm"]),
|
| 1139 |
+
}
|
| 1140 |
+
for item in data["markets"]
|
| 1141 |
+
]
|
| 1142 |
+
lines = [
|
| 1143 |
+
f"Dex: {data['dex'] or 'first-perp-dex'}",
|
| 1144 |
+
f"Markets returned: {len(data['markets'])} of {data['count']}",
|
| 1145 |
+
"",
|
| 1146 |
+
_render_table(
|
| 1147 |
+
[
|
| 1148 |
+
("Coin", "coin"),
|
| 1149 |
+
("Mark", "mark_px"),
|
| 1150 |
+
("Chg", "change_pct"),
|
| 1151 |
+
("Funding", "funding"),
|
| 1152 |
+
("OI", "open_interest"),
|
| 1153 |
+
("24h Vol", "day_ntl_vlm"),
|
| 1154 |
+
],
|
| 1155 |
+
rows,
|
| 1156 |
+
),
|
| 1157 |
+
]
|
| 1158 |
+
return "\n".join(lines)
|
| 1159 |
+
|
| 1160 |
+
|
| 1161 |
+
def render_spots(data: Dict[str, Any]) -> str:
|
| 1162 |
+
rows = [
|
| 1163 |
+
{
|
| 1164 |
+
"pair": item["display_name"],
|
| 1165 |
+
"mark_px": _format_price(item["mark_px"]),
|
| 1166 |
+
"change_pct": _format_percent(item["change_pct"]),
|
| 1167 |
+
"day_ntl_vlm": _compact_number(item["day_ntl_vlm"]),
|
| 1168 |
+
}
|
| 1169 |
+
for item in data["pairs"]
|
| 1170 |
+
]
|
| 1171 |
+
return "\n".join(
|
| 1172 |
+
[
|
| 1173 |
+
f"Spot pairs returned: {len(data['pairs'])} of {data['count']}",
|
| 1174 |
+
"",
|
| 1175 |
+
_render_table(
|
| 1176 |
+
[
|
| 1177 |
+
("Pair", "pair"),
|
| 1178 |
+
("Mark", "mark_px"),
|
| 1179 |
+
("Chg", "change_pct"),
|
| 1180 |
+
("24h Vol", "day_ntl_vlm"),
|
| 1181 |
+
],
|
| 1182 |
+
rows,
|
| 1183 |
+
),
|
| 1184 |
+
]
|
| 1185 |
+
)
|
| 1186 |
+
|
| 1187 |
+
|
| 1188 |
+
def render_candles(data: Dict[str, Any]) -> str:
|
| 1189 |
+
rows = [
|
| 1190 |
+
{
|
| 1191 |
+
"time": _format_timestamp_ms(item["time"]),
|
| 1192 |
+
"open": _format_price(item["open"]),
|
| 1193 |
+
"high": _format_price(item["high"]),
|
| 1194 |
+
"low": _format_price(item["low"]),
|
| 1195 |
+
"close": _format_price(item["close"]),
|
| 1196 |
+
"volume": _compact_number(item["volume"]),
|
| 1197 |
+
}
|
| 1198 |
+
for item in data["candles"]
|
| 1199 |
+
]
|
| 1200 |
+
summary = data.get("summary") or {}
|
| 1201 |
+
lines = [
|
| 1202 |
+
f"Coin: {data['coin']}",
|
| 1203 |
+
f"Interval: {data['interval']}",
|
| 1204 |
+
f"Hours: {data['hours']}",
|
| 1205 |
+
f"Candles returned: {len(data['candles'])} of {data['count']}",
|
| 1206 |
+
]
|
| 1207 |
+
if summary:
|
| 1208 |
+
lines.extend(
|
| 1209 |
+
[
|
| 1210 |
+
f"Open -> Close: {_format_price(summary.get('open'))} -> {_format_price(summary.get('close'))}",
|
| 1211 |
+
f"Range: {_format_price(summary.get('low'))} to {_format_price(summary.get('high'))}",
|
| 1212 |
+
f"Change: {_format_percent(summary.get('change_pct'))}",
|
| 1213 |
+
]
|
| 1214 |
+
)
|
| 1215 |
+
lines.extend(
|
| 1216 |
+
[
|
| 1217 |
+
"",
|
| 1218 |
+
_render_table(
|
| 1219 |
+
[
|
| 1220 |
+
("Time", "time"),
|
| 1221 |
+
("Open", "open"),
|
| 1222 |
+
("High", "high"),
|
| 1223 |
+
("Low", "low"),
|
| 1224 |
+
("Close", "close"),
|
| 1225 |
+
("Volume", "volume"),
|
| 1226 |
+
],
|
| 1227 |
+
rows,
|
| 1228 |
+
),
|
| 1229 |
+
]
|
| 1230 |
+
)
|
| 1231 |
+
return "\n".join(lines)
|
| 1232 |
+
|
| 1233 |
+
|
| 1234 |
+
def render_funding(data: Dict[str, Any]) -> str:
|
| 1235 |
+
rows = [
|
| 1236 |
+
{
|
| 1237 |
+
"time": _format_timestamp_ms(item["time"]),
|
| 1238 |
+
"coin": item["coin"],
|
| 1239 |
+
"funding": _format_fraction_percent(item["funding_rate"]),
|
| 1240 |
+
"premium": _format_fraction_percent(item["premium"]),
|
| 1241 |
+
}
|
| 1242 |
+
for item in data["history"]
|
| 1243 |
+
]
|
| 1244 |
+
lines = [
|
| 1245 |
+
f"Coin: {data['coin']}",
|
| 1246 |
+
f"Hours: {data['hours']}",
|
| 1247 |
+
f"Entries returned: {len(data['history'])} of {data['count']}",
|
| 1248 |
+
f"Average funding: {_format_fraction_percent(data['average_funding_rate'])}",
|
| 1249 |
+
"",
|
| 1250 |
+
_render_table(
|
| 1251 |
+
[
|
| 1252 |
+
("Time", "time"),
|
| 1253 |
+
("Coin", "coin"),
|
| 1254 |
+
("Funding", "funding"),
|
| 1255 |
+
("Premium", "premium"),
|
| 1256 |
+
],
|
| 1257 |
+
rows,
|
| 1258 |
+
),
|
| 1259 |
+
]
|
| 1260 |
+
return "\n".join(lines)
|
| 1261 |
+
|
| 1262 |
+
|
| 1263 |
+
def render_l2(data: Dict[str, Any]) -> str:
|
| 1264 |
+
bid_rows = [
|
| 1265 |
+
{"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"}
|
| 1266 |
+
for item in data["bids"]
|
| 1267 |
+
]
|
| 1268 |
+
ask_rows = [
|
| 1269 |
+
{"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"}
|
| 1270 |
+
for item in data["asks"]
|
| 1271 |
+
]
|
| 1272 |
+
lines = [
|
| 1273 |
+
f"Coin: {data['coin']}",
|
| 1274 |
+
f"Book time: {_format_timestamp_ms(data['time'])}",
|
| 1275 |
+
"",
|
| 1276 |
+
"Bids",
|
| 1277 |
+
_render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], bid_rows),
|
| 1278 |
+
"",
|
| 1279 |
+
"Asks",
|
| 1280 |
+
_render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], ask_rows),
|
| 1281 |
+
]
|
| 1282 |
+
return "\n".join(lines)
|
| 1283 |
+
|
| 1284 |
+
|
| 1285 |
+
def render_state(data: Dict[str, Any]) -> str:
|
| 1286 |
+
summary = data["summary"]
|
| 1287 |
+
position_rows = [
|
| 1288 |
+
{
|
| 1289 |
+
"coin": item["coin"],
|
| 1290 |
+
"size": item["size"],
|
| 1291 |
+
"entry_px": _format_price(item["entry_px"]),
|
| 1292 |
+
"position_value": _compact_number(item["position_value"]),
|
| 1293 |
+
"unrealized_pnl": _compact_number(item["unrealized_pnl"]),
|
| 1294 |
+
"roe": _format_fraction_percent(item["return_on_equity"], 2),
|
| 1295 |
+
"liq": _format_price(item["liquidation_px"]),
|
| 1296 |
+
"lev": f"{item['leverage'] or '-'}x",
|
| 1297 |
+
}
|
| 1298 |
+
for item in data["positions"]
|
| 1299 |
+
]
|
| 1300 |
+
|
| 1301 |
+
lines = [
|
| 1302 |
+
f"User: {data['user']}",
|
| 1303 |
+
f"Dex: {data['dex'] or 'first-perp-dex'}",
|
| 1304 |
+
f"Account value: {summary.get('account_value') or '-'}",
|
| 1305 |
+
f"Total notional position: {summary.get('total_ntl_pos') or '-'}",
|
| 1306 |
+
f"Withdrawable: {summary.get('withdrawable') or '-'}",
|
| 1307 |
+
f"Positions: {len(data['positions'])}",
|
| 1308 |
+
]
|
| 1309 |
+
if position_rows:
|
| 1310 |
+
lines.extend(
|
| 1311 |
+
[
|
| 1312 |
+
"",
|
| 1313 |
+
_render_table(
|
| 1314 |
+
[
|
| 1315 |
+
("Coin", "coin"),
|
| 1316 |
+
("Size", "size"),
|
| 1317 |
+
("Entry", "entry_px"),
|
| 1318 |
+
("Pos Val", "position_value"),
|
| 1319 |
+
("uPnL", "unrealized_pnl"),
|
| 1320 |
+
("ROE", "roe"),
|
| 1321 |
+
("Liq", "liq"),
|
| 1322 |
+
("Lev", "lev"),
|
| 1323 |
+
],
|
| 1324 |
+
position_rows,
|
| 1325 |
+
),
|
| 1326 |
+
]
|
| 1327 |
+
)
|
| 1328 |
+
return "\n".join(lines)
|
| 1329 |
+
|
| 1330 |
+
|
| 1331 |
+
def render_spot_balances(data: Dict[str, Any]) -> str:
|
| 1332 |
+
rows = [
|
| 1333 |
+
{
|
| 1334 |
+
"coin": item["coin"],
|
| 1335 |
+
"total": _compact_number(item["total"]),
|
| 1336 |
+
"hold": _compact_number(item["hold"]),
|
| 1337 |
+
"entry_ntl": _compact_number(item["entry_ntl"]),
|
| 1338 |
+
}
|
| 1339 |
+
for item in data["balances"]
|
| 1340 |
+
]
|
| 1341 |
+
return "\n".join(
|
| 1342 |
+
[
|
| 1343 |
+
f"User: {data['user']}",
|
| 1344 |
+
f"Balances returned: {len(data['balances'])} of {data['count']}",
|
| 1345 |
+
"",
|
| 1346 |
+
_render_table(
|
| 1347 |
+
[
|
| 1348 |
+
("Coin", "coin"),
|
| 1349 |
+
("Total", "total"),
|
| 1350 |
+
("Hold", "hold"),
|
| 1351 |
+
("Entry Ntl", "entry_ntl"),
|
| 1352 |
+
],
|
| 1353 |
+
rows,
|
| 1354 |
+
),
|
| 1355 |
+
]
|
| 1356 |
+
)
|
| 1357 |
+
|
| 1358 |
+
|
| 1359 |
+
def render_fills(data: Dict[str, Any]) -> str:
|
| 1360 |
+
rows = [
|
| 1361 |
+
{
|
| 1362 |
+
"time": _format_timestamp_ms(item["time"]),
|
| 1363 |
+
"coin": item["coin"],
|
| 1364 |
+
"dir": item["dir"],
|
| 1365 |
+
"px": _format_price(item["px"]),
|
| 1366 |
+
"sz": _compact_number(item["sz"]),
|
| 1367 |
+
"closed_pnl": _compact_number(item["closed_pnl"]),
|
| 1368 |
+
"fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(),
|
| 1369 |
+
}
|
| 1370 |
+
for item in data["fills"]
|
| 1371 |
+
]
|
| 1372 |
+
lines = [
|
| 1373 |
+
f"User: {data['user']}",
|
| 1374 |
+
f"Aggregate by time: {data['aggregate_by_time']}",
|
| 1375 |
+
f"Fills returned: {len(data['fills'])} of {data['count']}",
|
| 1376 |
+
"",
|
| 1377 |
+
_render_table(
|
| 1378 |
+
[
|
| 1379 |
+
("Time", "time"),
|
| 1380 |
+
("Coin", "coin"),
|
| 1381 |
+
("Dir", "dir"),
|
| 1382 |
+
("Px", "px"),
|
| 1383 |
+
("Sz", "sz"),
|
| 1384 |
+
("Closed PnL", "closed_pnl"),
|
| 1385 |
+
("Fee", "fee"),
|
| 1386 |
+
],
|
| 1387 |
+
rows,
|
| 1388 |
+
),
|
| 1389 |
+
]
|
| 1390 |
+
return "\n".join(lines)
|
| 1391 |
+
|
| 1392 |
+
|
| 1393 |
+
def render_orders(data: Dict[str, Any]) -> str:
|
| 1394 |
+
rows = [
|
| 1395 |
+
{
|
| 1396 |
+
"time": _format_timestamp_ms(item["timestamp"]),
|
| 1397 |
+
"coin": item["coin"],
|
| 1398 |
+
"side": item["side"],
|
| 1399 |
+
"limit_px": _format_price(item["limit_px"]),
|
| 1400 |
+
"size": _compact_number(item["size"]),
|
| 1401 |
+
"status": item["status"],
|
| 1402 |
+
"oid": item["oid"] or "-",
|
| 1403 |
+
}
|
| 1404 |
+
for item in data["orders"]
|
| 1405 |
+
]
|
| 1406 |
+
return "\n".join(
|
| 1407 |
+
[
|
| 1408 |
+
f"User: {data['user']}",
|
| 1409 |
+
f"Orders returned: {len(data['orders'])} of {data['count']}",
|
| 1410 |
+
"",
|
| 1411 |
+
_render_table(
|
| 1412 |
+
[
|
| 1413 |
+
("Time", "time"),
|
| 1414 |
+
("Coin", "coin"),
|
| 1415 |
+
("Side", "side"),
|
| 1416 |
+
("Px", "limit_px"),
|
| 1417 |
+
("Sz", "size"),
|
| 1418 |
+
("Status", "status"),
|
| 1419 |
+
("OID", "oid"),
|
| 1420 |
+
],
|
| 1421 |
+
rows,
|
| 1422 |
+
),
|
| 1423 |
+
]
|
| 1424 |
+
)
|
| 1425 |
+
|
| 1426 |
+
|
| 1427 |
+
def render_review(data: Dict[str, Any]) -> str:
|
| 1428 |
+
summary = data["summary"]
|
| 1429 |
+
coin_rows = [
|
| 1430 |
+
{
|
| 1431 |
+
"coin": item["coin"],
|
| 1432 |
+
"fills": item["fill_count"],
|
| 1433 |
+
"net": _compact_number(item["net_after_fees"]),
|
| 1434 |
+
"win_rate": _format_percent(item["win_rate_pct"]),
|
| 1435 |
+
"trend": _format_percent(item["market_context"].get("price_change_pct")),
|
| 1436 |
+
"funding": _format_fraction_percent(item["market_context"].get("average_funding_rate")),
|
| 1437 |
+
"bias": item["open_bias"],
|
| 1438 |
+
}
|
| 1439 |
+
for item in data["coin_reviews"]
|
| 1440 |
+
]
|
| 1441 |
+
recent_rows = [
|
| 1442 |
+
{
|
| 1443 |
+
"time": _format_timestamp_ms(item["time"]),
|
| 1444 |
+
"coin": item["coin"],
|
| 1445 |
+
"dir": item["dir"],
|
| 1446 |
+
"px": _format_price(item["px"]),
|
| 1447 |
+
"sz": _compact_number(item["sz"]),
|
| 1448 |
+
"closed_pnl": _compact_number(item["closed_pnl"]),
|
| 1449 |
+
"fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(),
|
| 1450 |
+
}
|
| 1451 |
+
for item in data["recent_fills"]
|
| 1452 |
+
]
|
| 1453 |
+
|
| 1454 |
+
lines = [
|
| 1455 |
+
f"User: {data['user']}",
|
| 1456 |
+
f"Review window: {data['hours']} hours",
|
| 1457 |
+
f"Coin filter: {data['coin_filter'] or 'all traded coins'}",
|
| 1458 |
+
f"Fills analyzed: {summary['fill_count']}",
|
| 1459 |
+
f"Unique coins: {summary['unique_coins']}",
|
| 1460 |
+
f"Realized PnL: {_compact_number(summary['realized_pnl'])}",
|
| 1461 |
+
f"Fees: {_compact_number(summary['total_fees'])}",
|
| 1462 |
+
f"Net after fees: {_compact_number(summary['net_after_fees'])}",
|
| 1463 |
+
f"Win rate: {_format_percent(summary['win_rate_pct'])}",
|
| 1464 |
+
]
|
| 1465 |
+
|
| 1466 |
+
if data["findings"]:
|
| 1467 |
+
lines.extend(["", "Findings"])
|
| 1468 |
+
for finding in data["findings"]:
|
| 1469 |
+
lines.append(f"- {finding}")
|
| 1470 |
+
|
| 1471 |
+
if coin_rows:
|
| 1472 |
+
lines.extend(
|
| 1473 |
+
[
|
| 1474 |
+
"",
|
| 1475 |
+
"Coin Breakdown",
|
| 1476 |
+
_render_table(
|
| 1477 |
+
[
|
| 1478 |
+
("Coin", "coin"),
|
| 1479 |
+
("Fills", "fills"),
|
| 1480 |
+
("Net", "net"),
|
| 1481 |
+
("Win Rate", "win_rate"),
|
| 1482 |
+
("Trend", "trend"),
|
| 1483 |
+
("Funding", "funding"),
|
| 1484 |
+
("Bias", "bias"),
|
| 1485 |
+
],
|
| 1486 |
+
coin_rows,
|
| 1487 |
+
),
|
| 1488 |
+
]
|
| 1489 |
+
)
|
| 1490 |
+
|
| 1491 |
+
if recent_rows:
|
| 1492 |
+
lines.extend(
|
| 1493 |
+
[
|
| 1494 |
+
"",
|
| 1495 |
+
"Recent Fills",
|
| 1496 |
+
_render_table(
|
| 1497 |
+
[
|
| 1498 |
+
("Time", "time"),
|
| 1499 |
+
("Coin", "coin"),
|
| 1500 |
+
("Dir", "dir"),
|
| 1501 |
+
("Px", "px"),
|
| 1502 |
+
("Sz", "sz"),
|
| 1503 |
+
("Closed PnL", "closed_pnl"),
|
| 1504 |
+
("Fee", "fee"),
|
| 1505 |
+
],
|
| 1506 |
+
recent_rows,
|
| 1507 |
+
),
|
| 1508 |
+
]
|
| 1509 |
+
)
|
| 1510 |
+
|
| 1511 |
+
return "\n".join(lines)
|
| 1512 |
+
|
| 1513 |
+
|
| 1514 |
+
def render_export(data: Dict[str, Any]) -> str:
|
| 1515 |
+
summary = data["summary"]
|
| 1516 |
+
return "\n".join(
|
| 1517 |
+
[
|
| 1518 |
+
f"Coin: {data['coin']}",
|
| 1519 |
+
f"Interval: {data['interval']}",
|
| 1520 |
+
f"Hours: {data['hours']}",
|
| 1521 |
+
f"Schema: {data['schema_version']}",
|
| 1522 |
+
f"Output: {data['output_path']}",
|
| 1523 |
+
f"Candles: {summary['candle_count']}",
|
| 1524 |
+
f"Funding samples: {summary['funding_count']}",
|
| 1525 |
+
f"Window open -> close: {_format_price(summary.get('window_open'))} -> {_format_price(summary.get('window_close'))}",
|
| 1526 |
+
f"Price change: {_format_percent(summary.get('price_change_pct'))}",
|
| 1527 |
+
f"Average funding: {_format_fraction_percent(summary.get('average_funding_rate'))}",
|
| 1528 |
+
]
|
| 1529 |
+
)
|
| 1530 |
+
|
| 1531 |
+
|
| 1532 |
+
def _add_json_flag(parser: argparse.ArgumentParser) -> None:
|
| 1533 |
+
parser.add_argument("--json", action="store_true", help="Print raw JSON output")
|
| 1534 |
+
|
| 1535 |
+
|
| 1536 |
+
def build_parser() -> argparse.ArgumentParser:
|
| 1537 |
+
parser = argparse.ArgumentParser(description="Hyperliquid CLI Tool for Hermes Agent")
|
| 1538 |
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
| 1539 |
+
|
| 1540 |
+
dexs = subparsers.add_parser("dexs", help="List available perpetual dexs")
|
| 1541 |
+
_add_json_flag(dexs)
|
| 1542 |
+
dexs.set_defaults(func=run_dexs, renderer=render_dexs)
|
| 1543 |
+
|
| 1544 |
+
markets = subparsers.add_parser("markets", help="List perpetual market contexts")
|
| 1545 |
+
markets.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex")
|
| 1546 |
+
markets.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
|
| 1547 |
+
markets.add_argument(
|
| 1548 |
+
"--sort",
|
| 1549 |
+
choices=["volume", "oi", "funding_abs", "change_abs", "name"],
|
| 1550 |
+
default="volume",
|
| 1551 |
+
help="Sort mode",
|
| 1552 |
+
)
|
| 1553 |
+
_add_json_flag(markets)
|
| 1554 |
+
markets.set_defaults(func=run_markets, renderer=render_markets)
|
| 1555 |
+
|
| 1556 |
+
spots = subparsers.add_parser("spots", help="List spot market contexts")
|
| 1557 |
+
spots.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
|
| 1558 |
+
spots.add_argument(
|
| 1559 |
+
"--sort",
|
| 1560 |
+
choices=["volume", "change_abs", "name"],
|
| 1561 |
+
default="volume",
|
| 1562 |
+
help="Sort mode",
|
| 1563 |
+
)
|
| 1564 |
+
_add_json_flag(spots)
|
| 1565 |
+
spots.set_defaults(func=run_spots, renderer=render_spots)
|
| 1566 |
+
|
| 1567 |
+
candles = subparsers.add_parser("candles", help="Fetch candle history for a market")
|
| 1568 |
+
candles.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"')
|
| 1569 |
+
candles.add_argument("--interval", default="1h", help="Candle interval, e.g. 1m, 15m, 1h, 4h, 1d")
|
| 1570 |
+
candles.add_argument("--hours", type=float, default=24.0, help="Lookback window in hours")
|
| 1571 |
+
candles.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
|
| 1572 |
+
_add_json_flag(candles)
|
| 1573 |
+
candles.set_defaults(func=run_candles, renderer=render_candles)
|
| 1574 |
+
|
| 1575 |
+
funding = subparsers.add_parser("funding", help="Fetch funding history for a perp market")
|
| 1576 |
+
funding.add_argument("coin", help='Coin name, e.g. "BTC" or "mydex:COIN"')
|
| 1577 |
+
funding.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours")
|
| 1578 |
+
funding.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
|
| 1579 |
+
_add_json_flag(funding)
|
| 1580 |
+
funding.set_defaults(func=run_funding, renderer=render_funding)
|
| 1581 |
+
|
| 1582 |
+
l2 = subparsers.add_parser("l2", help="Inspect the current L2 book for a market")
|
| 1583 |
+
l2.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC"')
|
| 1584 |
+
l2.add_argument("--levels", type=int, default=10, help="Levels per side to display")
|
| 1585 |
+
l2.add_argument("--n-sig-figs", type=int, default=None, help="Optional server-side book aggregation")
|
| 1586 |
+
l2.add_argument("--mantissa", type=int, default=None, help="Optional mantissa when using nSigFigs")
|
| 1587 |
+
_add_json_flag(l2)
|
| 1588 |
+
l2.set_defaults(func=run_l2, renderer=render_l2)
|
| 1589 |
+
|
| 1590 |
+
state = subparsers.add_parser("state", help="Inspect a user's perp account state")
|
| 1591 |
+
state.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
|
| 1592 |
+
state.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex")
|
| 1593 |
+
_add_json_flag(state)
|
| 1594 |
+
state.set_defaults(func=run_state, renderer=render_state)
|
| 1595 |
+
|
| 1596 |
+
spot_balances = subparsers.add_parser("spot-balances", help="Inspect a user's spot token balances")
|
| 1597 |
+
spot_balances.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
|
| 1598 |
+
spot_balances.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
|
| 1599 |
+
_add_json_flag(spot_balances)
|
| 1600 |
+
spot_balances.set_defaults(func=run_spot_balances, renderer=render_spot_balances)
|
| 1601 |
+
|
| 1602 |
+
fills = subparsers.add_parser("fills", help="Inspect a user's recent fills")
|
| 1603 |
+
fills.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
|
| 1604 |
+
fills.add_argument("--hours", type=float, default=None, help="Optional time window; uses userFillsByTime")
|
| 1605 |
+
fills.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
|
| 1606 |
+
fills.add_argument(
|
| 1607 |
+
"--aggregate-by-time",
|
| 1608 |
+
action="store_true",
|
| 1609 |
+
help="Aggregate partial fills when the API supports it",
|
| 1610 |
+
)
|
| 1611 |
+
_add_json_flag(fills)
|
| 1612 |
+
fills.set_defaults(func=run_fills, renderer=render_fills)
|
| 1613 |
+
|
| 1614 |
+
orders = subparsers.add_parser("orders", help="Inspect a user's historical orders")
|
| 1615 |
+
orders.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
|
| 1616 |
+
orders.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
|
| 1617 |
+
_add_json_flag(orders)
|
| 1618 |
+
orders.set_defaults(func=run_orders, renderer=render_orders)
|
| 1619 |
+
|
| 1620 |
+
review = subparsers.add_parser("review", help="Generate a lightweight post-trade review from recent fills")
|
| 1621 |
+
review.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
|
| 1622 |
+
review.add_argument("--coin", default="", help="Optional exact coin filter, e.g. BTC or PURR/USDC")
|
| 1623 |
+
review.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours")
|
| 1624 |
+
review.add_argument("--fills", type=int, default=50, help="Maximum fills to analyze")
|
| 1625 |
+
review.add_argument("--recent", type=int, default=10, help="Recent fills to display in the review")
|
| 1626 |
+
review.add_argument("--interval", default="1h", help="Candle interval for market context")
|
| 1627 |
+
review.add_argument(
|
| 1628 |
+
"--aggregate-by-time",
|
| 1629 |
+
action="store_true",
|
| 1630 |
+
help="Aggregate partial fills when the API supports it",
|
| 1631 |
+
)
|
| 1632 |
+
_add_json_flag(review)
|
| 1633 |
+
review.set_defaults(func=run_review, renderer=render_review)
|
| 1634 |
+
|
| 1635 |
+
export = subparsers.add_parser("export", help="Export normalized candles and funding history to a JSON file")
|
| 1636 |
+
export.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"')
|
| 1637 |
+
export.add_argument("--interval", default="1h", help="Candle interval for the exported dataset")
|
| 1638 |
+
export.add_argument("--hours", type=float, default=168.0, help="Lookback window in hours")
|
| 1639 |
+
export.add_argument("--end-time-ms", type=int, default=None, help="Optional fixed end time for reproducible exports")
|
| 1640 |
+
export.add_argument("--output", default="", help="Path to the JSON export file")
|
| 1641 |
+
_add_json_flag(export)
|
| 1642 |
+
export.set_defaults(func=run_export, renderer=render_export)
|
| 1643 |
+
|
| 1644 |
+
return parser
|
| 1645 |
+
|
| 1646 |
+
|
| 1647 |
+
def main(argv: Optional[List[str]] = None) -> int:
|
| 1648 |
+
parser = build_parser()
|
| 1649 |
+
args = parser.parse_args(argv)
|
| 1650 |
+
|
| 1651 |
+
payload = args.func(args)
|
| 1652 |
+
if args.json:
|
| 1653 |
+
print(json.dumps(payload, indent=2))
|
| 1654 |
+
else:
|
| 1655 |
+
print(args.renderer(payload))
|
| 1656 |
+
return 0
|
| 1657 |
+
|
| 1658 |
+
|
| 1659 |
+
if __name__ == "__main__":
|
| 1660 |
+
raise SystemExit(main())
|
optional-skills/creative/ai-presenter-video/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
MIT License
|
| 2 |
+
|
| 3 |
+
Copyright (c) 2026 lanshu
|
| 4 |
+
|
| 5 |
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
| 6 |
+
of this software and associated documentation files (the "Software"), to deal
|
| 7 |
+
in the Software without restriction, including without limitation the rights
|
| 8 |
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
| 9 |
+
copies of the Software, and to permit persons to whom the Software is
|
| 10 |
+
furnished to do so, subject to the following conditions:
|
| 11 |
+
|
| 12 |
+
The above copyright notice and this permission notice shall be included in all
|
| 13 |
+
copies or substantial portions of the Software.
|
| 14 |
+
|
| 15 |
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
| 16 |
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
| 17 |
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
| 18 |
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
| 19 |
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
| 20 |
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
| 21 |
+
SOFTWARE.
|
optional-skills/creative/ai-presenter-video/SKILL.md
ADDED
|
@@ -0,0 +1,196 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: ai-presenter-video
|
| 3 |
+
description: "Make a verified AI presenter video from script + image."
|
| 4 |
+
version: 1.0.0
|
| 5 |
+
author: cclank (https://github.com/cclank/lanshu-create-ai-presenter-video), ported by Hermes Agent
|
| 6 |
+
license: MIT
|
| 7 |
+
platforms: [linux, macos]
|
| 8 |
+
required_commands: [ffmpeg, ffprobe, python3]
|
| 9 |
+
metadata:
|
| 10 |
+
hermes:
|
| 11 |
+
tags: [video, presenter, avatar, lipsync, tts, captions, creative]
|
| 12 |
+
category: creative
|
| 13 |
+
homepage: https://github.com/cclank/lanshu-create-ai-presenter-video
|
| 14 |
+
related_skills: [hyperframes, kanban-video-orchestrator, comfyui]
|
| 15 |
+
---
|
| 16 |
+
|
| 17 |
+
# AI Presenter Video
|
| 18 |
+
|
| 19 |
+
Turn a topic (or finished script) plus ONE authorized adult presenter image
|
| 20 |
+
into a complete, publish-ready presenter-led video: locked narration, avatar
|
| 21 |
+
generation with lip-sync QA, captions, deterministic editing, loudness-normalized
|
| 22 |
+
master/share encodes, and machine + visual acceptance reports.
|
| 23 |
+
|
| 24 |
+
Use this skill for new presenter videos AND for continuing, revising,
|
| 25 |
+
captioning, lip-sync-repairing, or re-exporting an existing presenter-video
|
| 26 |
+
job. The workflow is provider-neutral: pick generation capabilities from what
|
| 27 |
+
is actually available in the session (FAL video/image models via
|
| 28 |
+
`image_generate` and the video-gen plugin, TTS via `text_to_speech`, ASR via
|
| 29 |
+
the whisper/STT tooling, ffmpeg for everything deterministic).
|
| 30 |
+
|
| 31 |
+
> Ported from cclank/lanshu-create-ai-presenter-video (MIT). Upstream body
|
| 32 |
+
> kept substantively verbatim in `references/`; Hermes adaptations live in
|
| 33 |
+
> this hub file. Scripts are deterministic (no network, no credentials).
|
| 34 |
+
|
| 35 |
+
## Hermes adaptations (read first)
|
| 36 |
+
|
| 37 |
+
- **Skill dir resolution** — upstream hardcoded its own agent's skills path.
|
| 38 |
+
In Hermes the loader expands `${HERMES_SKILL_DIR}` to this skill's installed
|
| 39 |
+
directory, so every command below uses that token directly:
|
| 40 |
+
|
| 41 |
+
```bash
|
| 42 |
+
SKILL_DIR="${HERMES_SKILL_DIR}"
|
| 43 |
+
```
|
| 44 |
+
|
| 45 |
+
Shell variables do not persist between tool calls — re-paste the assignment
|
| 46 |
+
(or the expanded path) in each terminal call that uses it.
|
| 47 |
+
- **Capability mapping** — where the references say "a voice generation
|
| 48 |
+
capability", use `text_to_speech` (OpenAI/Edge/ElevenLabs per user config);
|
| 49 |
+
"presenter/avatar generation" → FAL image-to-video families (Kling, Wan,
|
| 50 |
+
MiniMax H3 etc.) through the configured video tooling, or an avatar/lipsync
|
| 51 |
+
endpoint the user has access to; "word-timestamp ASR" → whisper via the STT
|
| 52 |
+
tooling or `faster-whisper` in a venv; "deterministic compositor" → ffmpeg
|
| 53 |
+
filtergraphs, or the `hyperframes` skill when installed (the editing
|
| 54 |
+
reference has a HyperFrames section that maps directly onto it).
|
| 55 |
+
- **Visual QA** — do the "normal-speed visual review" steps with
|
| 56 |
+
`vision_analyze` on the generated contact sheet plus sampled frames
|
| 57 |
+
(identity, mouth timing, hands, blinking, continuity). Numeric checks come
|
| 58 |
+
from the scripts' ffprobe output.
|
| 59 |
+
- **Paid-generation consent** — remote avatar/TTS generation is billable.
|
| 60 |
+
Follow the upstream operating rules: before the first paid call state the
|
| 61 |
+
uploaded assets, requested seconds, known cost, pilot size, and retry
|
| 62 |
+
ceiling, and get the user's explicit go-ahead. Never upload the presenter
|
| 63 |
+
image to a remote provider before `remote_upload_approved` is true in
|
| 64 |
+
`job.json`.
|
| 65 |
+
- **Consent flags live under `input`** — `rights_confirmed`,
|
| 66 |
+
`adult_presenter_confirmed`, `remote_upload_approved`, and
|
| 67 |
+
`voice_clone_approved` sit inside the `input` object of `job.json` (init
|
| 68 |
+
flags set them; hand-editing must target `input.*`, not the job root).
|
| 69 |
+
`manual_input_review.*` sits at the root. `preflight.py` distinguishes
|
| 70 |
+
`errors` (block everything) from `remote_blockers` (block only remote
|
| 71 |
+
generation) — local script/audio work may proceed while remote is blocked.
|
| 72 |
+
|
| 73 |
+
## Workflow
|
| 74 |
+
|
| 75 |
+
1. **Start or resume a job.** New job:
|
| 76 |
+
|
| 77 |
+
```bash
|
| 78 |
+
python3 "$SKILL_DIR/scripts/init_job.py" \
|
| 79 |
+
--job-dir ~/Videos/my-presenter-video \
|
| 80 |
+
--presenter-image /path/to/presenter.png \
|
| 81 |
+
--topic "explain context engineering in one minute" \
|
| 82 |
+
--duration 60 --aspect 9:16 \
|
| 83 |
+
--rights-confirmed --adult-presenter-confirmed
|
| 84 |
+
```
|
| 85 |
+
|
| 86 |
+
Use `--script` for an existing script file; other flags: `--voice-sample`,
|
| 87 |
+
`--supporting-media`, `--width`, `--height`, `--fps`, `--watermark`,
|
| 88 |
+
`--cta`. For an existing job, read `job.json` + QA reports and resume from
|
| 89 |
+
the earliest unfinished state — never regenerate accepted work.
|
| 90 |
+
|
| 91 |
+
2. **Manual input review.** Actually look at the presenter image
|
| 92 |
+
(`vision_analyze`) and listen to any voice sample; record findings by
|
| 93 |
+
setting the `manual_input_review` booleans in `job.json`, e.g.:
|
| 94 |
+
|
| 95 |
+
```bash
|
| 96 |
+
python3 - <<'PY'
|
| 97 |
+
import json
|
| 98 |
+
p = "~/Videos/my-presenter-video/job.json" # expand ~ or use an absolute path
|
| 99 |
+
import os; p = os.path.expanduser(p)
|
| 100 |
+
j = json.load(open(p))
|
| 101 |
+
j["manual_input_review"].update(image_viewed=True, single_clear_face=True,
|
| 102 |
+
image_has_no_unwanted_text=True)
|
| 103 |
+
json.dump(j, open(p, "w"), indent=2)
|
| 104 |
+
PY
|
| 105 |
+
```
|
| 106 |
+
|
| 107 |
+
Then gate:
|
| 108 |
+
|
| 109 |
+
```bash
|
| 110 |
+
python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json
|
| 111 |
+
```
|
| 112 |
+
|
| 113 |
+
Proceed only when `ok: true`; do remote generation only when
|
| 114 |
+
`remote_ready: true`. Note: preflight also updates `job.json` in place
|
| 115 |
+
(records the report path) — re-read it after running rather than editing
|
| 116 |
+
a stale copy.
|
| 117 |
+
|
| 118 |
+
3. **Lock content and audio** — read `references/generation.md`. Script →
|
| 119 |
+
full narration via `text_to_speech` → ASR-verify the narration against the
|
| 120 |
+
script → record real durations. The locked audio is the master clock for
|
| 121 |
+
everything downstream.
|
| 122 |
+
|
| 123 |
+
4. **Plan and generate the presenter** — read `references/generation.md`.
|
| 124 |
+
Short low-cost pilot first; full run only after the pilot passes identity
|
| 125 |
+
and mouth-timing review.
|
| 126 |
+
|
| 127 |
+
5. **Edit** — read `references/editing.md`. Deterministic timeline driven by
|
| 128 |
+
the locked audio; captions and keyword callouts only after audio and media
|
| 129 |
+
are final.
|
| 130 |
+
|
| 131 |
+
6. **Verify and deliver** — read `references/qa-recovery.md`, render, then:
|
| 132 |
+
|
| 133 |
+
```bash
|
| 134 |
+
bash "$SKILL_DIR/scripts/finalize_delivery.sh" \
|
| 135 |
+
~/Videos/my-presenter-video/renders/rendered.mp4 \
|
| 136 |
+
~/Videos/my-presenter-video/outputs my-video
|
| 137 |
+
```
|
| 138 |
+
|
| 139 |
+
The finalizer preserves aspect ratio, runs two-pass loudness normalization
|
| 140 |
+
(program ≈ −16 LUFS), produces master + share encodes, decode-verifies
|
| 141 |
+
both, writes a delivery report JSON, and emits a nine-frame contact sheet.
|
| 142 |
+
Inspect the contact sheet with `vision_analyze` before claiming completion.
|
| 143 |
+
|
| 144 |
+
## Operating rules (non-negotiable)
|
| 145 |
+
|
| 146 |
+
- Confirm image rights, adult status, remote-upload approval, and
|
| 147 |
+
voice-cloning authorization before the relevant remote action.
|
| 148 |
+
- Never infer or clone a real person's voice from an image; use an authorized
|
| 149 |
+
sample or a stock TTS voice.
|
| 150 |
+
- Lock the complete narration before presenter generation, caption timing, or
|
| 151 |
+
final scene boundaries.
|
| 152 |
+
- Mute video sources in the final composition; only the approved narration
|
| 153 |
+
and intentional mix tracks carry audio.
|
| 154 |
+
- Preserve provider request bodies and task IDs (minus credentials/expiring
|
| 155 |
+
URLs). Poll interrupted work before resubmitting — avoid double billing.
|
| 156 |
+
- Stop after three rejected paid candidates and summarize the failure mode.
|
| 157 |
+
- Do not claim completion until the final files fully decode and the contact
|
| 158 |
+
sheet or full playback has been reviewed.
|
| 159 |
+
|
| 160 |
+
## Defaults for minimal input
|
| 161 |
+
|
| 162 |
+
9:16, 1080×1920, 30fps; topic-derived videos target 45–75s; stock voice when
|
| 163 |
+
no authorized sample; presenter-led layout with hook → 2–4 beats → close;
|
| 164 |
+
no music/CTA unless requested; language inferred from the request.
|
| 165 |
+
|
| 166 |
+
## Reference routing
|
| 167 |
+
|
| 168 |
+
- `references/generation.md` — intake, content, voice, capability selection,
|
| 169 |
+
presenter prompts, paid generation, provider changes.
|
| 170 |
+
- `references/editing.md` — timeline contract, openings/closes, captions,
|
| 171 |
+
keyword-callout presets, HyperFrames composition, exports.
|
| 172 |
+
- `references/qa-recovery.md` — technical acceptance, visual acceptance, and
|
| 173 |
+
recovery for lip-sync/identity/hands/exposure/freeze/caption/audio faults.
|
| 174 |
+
|
| 175 |
+
## Pitfalls
|
| 176 |
+
|
| 177 |
+
- `preflight.py` requires ffprobe; on a bare box install ffmpeg first.
|
| 178 |
+
- The consent booleans set by init flags land under `input.*`; editing them
|
| 179 |
+
at the job-json root silently does nothing (preflight keeps blocking).
|
| 180 |
+
- `finalize_delivery.sh` needs bash + jq + awk and a fully decodable input —
|
| 181 |
+
a truncated render fails the decode check by design, not by accident.
|
| 182 |
+
- Long avatar clips drift: prefer one continuous presenter source sliced on
|
| 183 |
+
the audio timeline over many regenerated chapter clips (identity drift
|
| 184 |
+
across regenerations is the #1 visual-QA failure).
|
| 185 |
+
- FAL i2v endpoints cap duration (typically 5–15s); plan chapter-level
|
| 186 |
+
presenter segments accordingly and reuse the pilot's seed/params for
|
| 187 |
+
consistency where the endpoint supports it.
|
| 188 |
+
|
| 189 |
+
## Verification
|
| 190 |
+
|
| 191 |
+
Validated hands-on (Aug 2026): `init_job.py` → `job.json` with correct state
|
| 192 |
+
machine; `preflight.py` correctly blocked on unreviewed inputs, flipped to
|
| 193 |
+
`ok: true` after review booleans, and kept `remote_ready: false` until
|
| 194 |
+
`input.remote_upload_approved`; `finalize_delivery.sh` on a synthetic 5s
|
| 195 |
+
1080×1920 render produced decode-verified master (631kbit/s) + share encodes,
|
| 196 |
+
delivery-report JSON, and a 9-frame contact sheet, exit 0.
|
optional-skills/creative/ai-presenter-video/assets/job.template.json
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"schema_version": 1,
|
| 3 |
+
"job_id": "replace-me",
|
| 4 |
+
"state": "intake",
|
| 5 |
+
"mode": "automation",
|
| 6 |
+
"input": {
|
| 7 |
+
"topic": "",
|
| 8 |
+
"script_path": "",
|
| 9 |
+
"presenter_image": "",
|
| 10 |
+
"voice_sample": "",
|
| 11 |
+
"supporting_media": [],
|
| 12 |
+
"rights_confirmed": false,
|
| 13 |
+
"adult_presenter_confirmed": false,
|
| 14 |
+
"remote_upload_approved": false,
|
| 15 |
+
"voice_clone_approved": false
|
| 16 |
+
},
|
| 17 |
+
"creative": {
|
| 18 |
+
"language": "auto",
|
| 19 |
+
"audience": "general",
|
| 20 |
+
"goal": "explain clearly",
|
| 21 |
+
"duration_target_s": 60,
|
| 22 |
+
"aspect": "9:16",
|
| 23 |
+
"width": 1080,
|
| 24 |
+
"height": 1920,
|
| 25 |
+
"fps": 30,
|
| 26 |
+
"style": "credible contemporary presenter",
|
| 27 |
+
"watermark": "",
|
| 28 |
+
"cta": ""
|
| 29 |
+
},
|
| 30 |
+
"voice": {
|
| 31 |
+
"strategy": "auto",
|
| 32 |
+
"voice_id": "",
|
| 33 |
+
"rate": 1.06,
|
| 34 |
+
"segment_lufs": -17,
|
| 35 |
+
"program_lufs": -16
|
| 36 |
+
},
|
| 37 |
+
"plan": {
|
| 38 |
+
"status": "draft",
|
| 39 |
+
"opening_target_s": 4,
|
| 40 |
+
"closing_target_s": 5,
|
| 41 |
+
"chapters": [],
|
| 42 |
+
"requested_generation_seconds": 0,
|
| 43 |
+
"estimated_cost": null,
|
| 44 |
+
"price_evidence_date": "",
|
| 45 |
+
"pilot_approved": false,
|
| 46 |
+
"paid_generation_approved": false,
|
| 47 |
+
"retry_ceiling": 3
|
| 48 |
+
},
|
| 49 |
+
"capabilities": {
|
| 50 |
+
"voice_generation": {},
|
| 51 |
+
"main_presenter": {},
|
| 52 |
+
"short_motion": {},
|
| 53 |
+
"lipsync_repair": {},
|
| 54 |
+
"word_timestamp_asr": {},
|
| 55 |
+
"timeline_compositor": {},
|
| 56 |
+
"encoder_qa": {}
|
| 57 |
+
},
|
| 58 |
+
"manual_input_review": {
|
| 59 |
+
"image_viewed": false,
|
| 60 |
+
"single_clear_face": false,
|
| 61 |
+
"image_has_no_unwanted_text": false,
|
| 62 |
+
"voice_sample_listened": false,
|
| 63 |
+
"single_clear_speaker": false
|
| 64 |
+
},
|
| 65 |
+
"artifacts": {
|
| 66 |
+
"script": "",
|
| 67 |
+
"beat_sheet": "",
|
| 68 |
+
"timeline": "",
|
| 69 |
+
"storyboard": "",
|
| 70 |
+
"final_audio": "",
|
| 71 |
+
"caption_json": "",
|
| 72 |
+
"rendered": "",
|
| 73 |
+
"master": "",
|
| 74 |
+
"share": ""
|
| 75 |
+
},
|
| 76 |
+
"qa": {
|
| 77 |
+
"preflight_report": "",
|
| 78 |
+
"asr_report": "",
|
| 79 |
+
"composition_report": "",
|
| 80 |
+
"delivery_report": "",
|
| 81 |
+
"manual_visual_review": ""
|
| 82 |
+
}
|
| 83 |
+
}
|
optional-skills/creative/ai-presenter-video/references/editing.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Editing
|
| 2 |
+
|
| 3 |
+
Read this file for the visual plan, deterministic timeline, openings, closes, screen demos, captions, keyword callouts, covers, previews, and exports.
|
| 4 |
+
|
| 5 |
+
## Visual routes
|
| 6 |
+
|
| 7 |
+
- **Presenter-led:** the presenter carries the explanation; add one concise visual idea per beat.
|
| 8 |
+
- **Screen-demo:** preserve real UI readability; introduce the presenter large at chapter starts, then shrink the same continuous video into a verified safe region.
|
| 9 |
+
- **Mixed explainer:** assign supporting media only where it proves or clarifies narration.
|
| 10 |
+
|
| 11 |
+
Do not fabricate product evidence. Label conceptual visuals clearly.
|
| 12 |
+
|
| 13 |
+
## Timeline contract
|
| 14 |
+
|
| 15 |
+
The locked narration defines duration and semantic boundaries. Every clip keeps three independent values:
|
| 16 |
+
|
| 17 |
+
- authored start in the final video;
|
| 18 |
+
- authored duration;
|
| 19 |
+
- source-media start.
|
| 20 |
+
|
| 21 |
+
When an opening changes length, shift authored starts while preserving presenter source offsets. Keep video sources muted and use approved external narration as the program clock. Prefer one continuous presenter source and source-time slices over regenerated chapter clips.
|
| 22 |
+
|
| 23 |
+
Use hard cuts at settled semantic pauses. Add transitions only when they clarify structure. Preserve a quiet tail so the last word, gesture, and mouth position finish naturally.
|
| 24 |
+
|
| 25 |
+
## Opening, body, and close
|
| 26 |
+
|
| 27 |
+
- Establish the topic and payoff within the first few seconds.
|
| 28 |
+
- Design the time-zero frame as a deliberate cover frame.
|
| 29 |
+
- Keep opening copy away from eyes, mouth, and the hand-motion path.
|
| 30 |
+
- Use the same visual system across the cover, chapters, captions, keywords, progress, and close.
|
| 31 |
+
- End with a conclusion or one requested next step. Do not add promotional copy without a brief requirement.
|
| 32 |
+
|
| 33 |
+
## Captions
|
| 34 |
+
|
| 35 |
+
Generate word timestamps from the final audio. Split into short semantic phrases, normally one readable line. A practical baseline is about `40ms` visual lead and `120ms` tail hold when neighboring phrases allow it.
|
| 36 |
+
|
| 37 |
+
Keep captions clear of the face, UI, watermark, progress line, and platform controls. Highlight one meaningful term per phrase. Make entrances and exits quick enough to preserve reading stability.
|
| 38 |
+
|
| 39 |
+
## Presenter-side keyword presets
|
| 40 |
+
|
| 41 |
+
Use keyword callouts to amplify selected spoken beats. Avoid repeating one identical card throughout the video.
|
| 42 |
+
|
| 43 |
+
Rotate a small family of presets such as:
|
| 44 |
+
|
| 45 |
+
- radial burst;
|
| 46 |
+
- tilted ribbon or sticker;
|
| 47 |
+
- hand-drawn circle or marker stroke;
|
| 48 |
+
- large/small type contrast;
|
| 49 |
+
- staggered word-chip cluster;
|
| 50 |
+
- double-layer outline lockup.
|
| 51 |
+
|
| 52 |
+
Bind each callout to a real spoken stress or ASR word anchor. Separate the entry timing of the kicker, main word, secondary word, marker, rays, and outline by a few frames. Let the callout settle briefly, then collapse before the next idea. Keep it inside a consistent presenter-side safe region and verify the complete motion path does not cover the face or hands.
|
| 53 |
+
|
| 54 |
+
## Composition and preview
|
| 55 |
+
|
| 56 |
+
Use a deterministic compositor available in the environment. For HyperFrames:
|
| 57 |
+
|
| 58 |
+
1. load the current HyperFrames workflow and domain instructions;
|
| 59 |
+
2. give all timed media explicit start, duration, track, and source offset;
|
| 60 |
+
3. run the required composition check with representative emphasis and transition samples;
|
| 61 |
+
4. inspect time zero, chapter cuts, layout changes, keyword beats, captions, close, and final frame;
|
| 62 |
+
5. open the final Studio preview and obtain approval before rendering;
|
| 63 |
+
6. render at delivery quality only after approval.
|
| 64 |
+
|
| 65 |
+
Measure the assembled stereo program after rendering. Mono narration duplicated into stereo can measure about 3 LU louder, so perform final program normalization from the rendered file.
|
optional-skills/creative/ai-presenter-video/references/generation.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Generation
|
| 2 |
+
|
| 3 |
+
Read this file for intake, content, narration, capability selection, paid generation, presenter prompts, or provider changes.
|
| 4 |
+
|
| 5 |
+
## Inputs and authorization
|
| 6 |
+
|
| 7 |
+
Required:
|
| 8 |
+
|
| 9 |
+
- a topic or script;
|
| 10 |
+
- one local presenter image with one clear adult face;
|
| 11 |
+
- confirmed image rights before remote upload;
|
| 12 |
+
- confirmed adult status from the user.
|
| 13 |
+
|
| 14 |
+
Optional:
|
| 15 |
+
|
| 16 |
+
- authorized voice sample;
|
| 17 |
+
- screen recordings, B-roll, images, charts, brand assets, or source links;
|
| 18 |
+
- audience, duration, language, aspect, style, watermark, music, CTA, provider preference, or previous episode.
|
| 19 |
+
|
| 20 |
+
Inspect the real image. Record visible anchors only: framing, hair, glasses, clothing, accessories, hands, furniture, background geometry, camera height, crop, light, exposure, white balance, embedded text, logos, occlusion, multiple faces, and resolution. Do not infer sensitive traits.
|
| 21 |
+
|
| 22 |
+
When a voice sample exists, listen for one speaker, audible speech duration, language, noise, echo, clipping, music, silence, and codec damage. Record whether cloning is authorized. Keep the original unchanged.
|
| 23 |
+
|
| 24 |
+
## Content and narration
|
| 25 |
+
|
| 26 |
+
For a topic, use one clear spine:
|
| 27 |
+
|
| 28 |
+
```text
|
| 29 |
+
hook → promise → 2–4 useful beats → synthesis → close
|
| 30 |
+
```
|
| 31 |
+
|
| 32 |
+
For a supplied script, preserve factual meaning while improving breath, pronunciation, sentence length, and transitions. Flag material factual edits for approval.
|
| 33 |
+
|
| 34 |
+
Generate the complete approved narration before visual work. Keep one voice identity and one synthesis configuration. Split only for operational limits or clean semantic sections. Preserve raw and normalized copies.
|
| 35 |
+
|
| 36 |
+
Run ASR against final audio. Review names, numbers, English tokens, omitted words, repeated words, and tail speech. Use actual audio durations for every later cut.
|
| 37 |
+
|
| 38 |
+
## Capability routing
|
| 39 |
+
|
| 40 |
+
Resolve capabilities at execution time:
|
| 41 |
+
|
| 42 |
+
| Capability | Acceptance priority |
|
| 43 |
+
|---|---|
|
| 44 |
+
| Voice generation | authorization, identity, pronunciation, rate control, clean audio |
|
| 45 |
+
| Main presenter | exact audio support, semantic lip sync, identity stability, required duration |
|
| 46 |
+
| Short motion | stable face, one controllable gesture, fixed camera, economical retry |
|
| 47 |
+
| Lip-sync repair | preserves accepted motion while replacing mouth timing with exact audio |
|
| 48 |
+
| Word-timestamp ASR | accurate word start/end times and reviewable output |
|
| 49 |
+
| Timeline compositor | explicit source offsets, frame-accurate seek, deterministic render |
|
| 50 |
+
| Encoder and QA | local probe, loudness, decode, black-frame and contact-sheet support |
|
| 51 |
+
|
| 52 |
+
Inspect current installed tools and official documentation when availability, duration, pricing, or request fields may have changed. Prefer a user-selected provider when it passes the gates. Otherwise choose the simplest available capability that does.
|
| 53 |
+
|
| 54 |
+
Record the actual provider, model, version, region, parameters, price evidence date, task ID, and sanitized request body in `job.json`. Ask before a provider change that affects cost, privacy, voice, appearance, or quality.
|
| 55 |
+
|
| 56 |
+
## Billing and pilot gate
|
| 57 |
+
|
| 58 |
+
Before the first remote or paid call, state:
|
| 59 |
+
|
| 60 |
+
- files or data being uploaded;
|
| 61 |
+
- capability and selected tool;
|
| 62 |
+
- requested seconds or units;
|
| 63 |
+
- known price or that the cost is unknown;
|
| 64 |
+
- pilot duration and retry ceiling;
|
| 65 |
+
- expected output and main risks.
|
| 66 |
+
|
| 67 |
+
Generate the smallest useful pilot. Continue to a full run only after technical checks and visual review pass. Do not generate a long clip when the edit uses only a short range.
|
| 68 |
+
|
| 69 |
+
## Presenter prompt structure
|
| 70 |
+
|
| 71 |
+
Write prompts in this order:
|
| 72 |
+
|
| 73 |
+
1. Bind the user image as the sole presenter and scene reference.
|
| 74 |
+
2. List only visible identity, clothing, accessory, camera, framing, background, light, exposure, and white-balance anchors.
|
| 75 |
+
3. Request realistic skin, hair, eye moisture, fabric, breathing, bilateral blinking, and restrained head motion.
|
| 76 |
+
4. Supply exact dialogue through the tool's supported audio or dialogue field.
|
| 77 |
+
5. Tie one physically plausible gesture to one phrase and approximate time.
|
| 78 |
+
6. Reserve a settled, closed-mouth tail.
|
| 79 |
+
7. Exclude identity, face, glasses, hair, wardrobe, skin tone, background, camera, lighting, finger, hand, dialogue, text, logo, watermark, and extra-person drift.
|
| 80 |
+
|
| 81 |
+
For the main presenter, prioritize mouth timing and identity. Keep hands low or outside frame. For an opening or close, one small gesture may carry the hook or CTA. Keep hands below the collarbone, away from the face and lens, and end the movement before the tail hold.
|
| 82 |
+
|
| 83 |
+
If the body performance is accepted but mouth timing is visibly late, preserve the motion plate and apply lip-sync repair with the exact locked audio and no duration extension.
|
optional-skills/creative/ai-presenter-video/references/qa-recovery.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# QA and recovery
|
| 2 |
+
|
| 3 |
+
Read this file before accepting generated media or delivery, and whenever a production fault appears.
|
| 4 |
+
|
| 5 |
+
## Acceptance gates
|
| 6 |
+
|
| 7 |
+
### Inputs
|
| 8 |
+
|
| 9 |
+
- Topic or script exists.
|
| 10 |
+
- Presenter image decodes and contains one reviewed adult face.
|
| 11 |
+
- Image rights, adult confirmation, and remote-upload permission are recorded.
|
| 12 |
+
- Any voice sample contains one authorized speaker.
|
| 13 |
+
- Supporting media is probed and its provenance is recorded.
|
| 14 |
+
|
| 15 |
+
### Audio
|
| 16 |
+
|
| 17 |
+
- Final ASR matches the intended script once, without material omissions or additions.
|
| 18 |
+
- Sections have consistent loudness, commonly near `-17 LUFS`.
|
| 19 |
+
- Assembled program loudness is commonly `-16 ± 0.5 LUFS` unless the destination specifies another target.
|
| 20 |
+
- No clipped words, doubled tracks, echo, clicks, unexpected silence, or truncated tail.
|
| 21 |
+
- Measure the final stereo file; section measurements alone are insufficient.
|
| 22 |
+
|
| 23 |
+
### Presenter
|
| 24 |
+
|
| 25 |
+
- Expected resolution, frame rate, duration, and decodable streams.
|
| 26 |
+
- No black frames, long exact-frame freezes, progressive darkening, or duration extension.
|
| 27 |
+
- Identity, face geometry, hair, glasses, clothing, accessories, background, crop, exposure, and white balance remain coherent.
|
| 28 |
+
- Mouth follows names, numbers, English tokens, plosives, and phrase endings.
|
| 29 |
+
- Blinks are sparse and bilateral; gestures occur once and settle; hands remain plausible and away from the face.
|
| 30 |
+
- Tail ends with a settled face and resting mouth.
|
| 31 |
+
|
| 32 |
+
### Composition and delivery
|
| 33 |
+
|
| 34 |
+
- No flash, duplicate presenter, source-time reset, missing overlay, overflow, face obstruction, caption collision, or unreadable UI.
|
| 35 |
+
- Opening, callouts, captions, watermark, progress, and platform safe zones remain compatible.
|
| 36 |
+
- Master and share files have the expected duration, dimensions, frame rate, codec, pixel format, and audio rate.
|
| 37 |
+
- Both files fully decode.
|
| 38 |
+
- Contact sheet covers opening, chapters, emphasis graphics, close, and final frame.
|
| 39 |
+
- Watch the complete video at normal speed before delivery.
|
| 40 |
+
|
| 41 |
+
## Recovery rules
|
| 42 |
+
|
| 43 |
+
### Interrupted remote task
|
| 44 |
+
|
| 45 |
+
Poll the saved task ID and download a succeeded result. Resubmit only after a confirmed failure or cancellation.
|
| 46 |
+
|
| 47 |
+
### Voice identity or loudness changes
|
| 48 |
+
|
| 49 |
+
Confirm one synthesis identity and configuration. Regenerate the mismatching section, normalize again, and rerun ASR. If the final render is louder than the source, confirm video is muted and apply whole-program two-pass loudness correction.
|
| 50 |
+
|
| 51 |
+
### Presenter changes between chapters
|
| 52 |
+
|
| 53 |
+
Use one continuous audio-driven source with source-time slices. When splitting is unavoidable, lock identity, framing, parameters, light, and quiet edge holds.
|
| 54 |
+
|
| 55 |
+
### Body motion works but mouth is late
|
| 56 |
+
|
| 57 |
+
Keep the accepted motion plate. Apply lip-sync repair with the exact locked audio and no duration extension. Check speech anchors at numbers, plosives, English tokens, and final syllables.
|
| 58 |
+
|
| 59 |
+
### Face, glasses, hands, or light drift
|
| 60 |
+
|
| 61 |
+
Retry from the original image with reduced motion and explicit camera, exposure, and white-balance locks. Simplify the gesture and keep hands low. Structural face or finger faults require regeneration; grading cannot correct them.
|
| 62 |
+
|
| 63 |
+
### Frozen picture-in-picture
|
| 64 |
+
|
| 65 |
+
Confirm the layout uses moving video, source offsets advance continuously, and no poster frame or identical-frame padding replaced the presenter.
|
| 66 |
+
|
| 67 |
+
### Captions or keyword graphics feel wrong
|
| 68 |
+
|
| 69 |
+
Regenerate timings from the final audio. Split by meaning, shorten visible phrases, and adjust small lead/hold margins. Bind keyword motion to actual spoken anchors and verify its complete path against the face, hands, UI, and captions.
|
| 70 |
+
|
| 71 |
+
### Three rejected paid candidates
|
| 72 |
+
|
| 73 |
+
Stop. Preserve candidates, prompts, task IDs, cost, and rejection notes. Summarize the recurring failure, remaining options, expected additional cost, and the single variable proposed for the next attempt.
|
optional-skills/creative/ai-presenter-video/scripts/finalize_delivery.sh
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
#!/usr/bin/env bash
|
| 2 |
+
|
| 3 |
+
set -euo pipefail
|
| 4 |
+
|
| 5 |
+
usage() {
|
| 6 |
+
printf 'Usage: %s rendered.mp4 output-dir output-stem\n' "$(basename "$0")" >&2
|
| 7 |
+
}
|
| 8 |
+
|
| 9 |
+
die() {
|
| 10 |
+
printf 'ERROR: %s\n' "$*" >&2
|
| 11 |
+
exit 1
|
| 12 |
+
}
|
| 13 |
+
|
| 14 |
+
[[ "$#" -eq 3 ]] || { usage; exit 64; }
|
| 15 |
+
|
| 16 |
+
INPUT="$1"
|
| 17 |
+
OUTPUT_DIR="$2"
|
| 18 |
+
STEM="$3"
|
| 19 |
+
|
| 20 |
+
[[ -f "$INPUT" && -s "$INPUT" ]] || die "input render is missing or empty: $INPUT"
|
| 21 |
+
[[ "$STEM" =~ ^[A-Za-z0-9._-]+$ ]] || die "output stem contains unsupported characters: $STEM"
|
| 22 |
+
|
| 23 |
+
for command in ffmpeg ffprobe jq mktemp awk sed; do
|
| 24 |
+
command -v "$command" >/dev/null 2>&1 || die "required command unavailable: $command"
|
| 25 |
+
done
|
| 26 |
+
|
| 27 |
+
mkdir -p "$OUTPUT_DIR"
|
| 28 |
+
OUTPUT_DIR="$(cd "$OUTPUT_DIR" && pwd -P)"
|
| 29 |
+
INPUT="$(cd "$(dirname "$INPUT")" && pwd -P)/$(basename "$INPUT")"
|
| 30 |
+
|
| 31 |
+
MASTER="$OUTPUT_DIR/${STEM}-master.mp4"
|
| 32 |
+
SHARE="$OUTPUT_DIR/${STEM}-share.mp4"
|
| 33 |
+
REPORT="$OUTPUT_DIR/${STEM}-delivery-report.json"
|
| 34 |
+
CONTACT="$OUTPUT_DIR/${STEM}-contact-sheet.png"
|
| 35 |
+
|
| 36 |
+
# Keep shared reports portable and avoid exposing the developer machine path.
|
| 37 |
+
INPUT_REPORT="$(basename "$INPUT")"
|
| 38 |
+
MASTER_REPORT="$(basename "$MASTER")"
|
| 39 |
+
SHARE_REPORT="$(basename "$SHARE")"
|
| 40 |
+
CONTACT_REPORT="$(basename "$CONTACT")"
|
| 41 |
+
|
| 42 |
+
for output in "$MASTER" "$SHARE" "$REPORT" "$CONTACT"; do
|
| 43 |
+
[[ ! -e "$output" ]] || die "refusing to overwrite existing output: $output"
|
| 44 |
+
done
|
| 45 |
+
|
| 46 |
+
TMP_ROOT="${TMPDIR:-/tmp}"
|
| 47 |
+
TMP_DIR="$(mktemp -d "${TMP_ROOT%/}/presenter-finalize.XXXXXX")"
|
| 48 |
+
trap 'rm -rf -- "$TMP_DIR"' EXIT INT TERM
|
| 49 |
+
|
| 50 |
+
STREAM_JSON="$TMP_DIR/source-probe.json"
|
| 51 |
+
ffprobe -v error -show_streams -show_format -of json "$INPUT" >"$STREAM_JSON"
|
| 52 |
+
jq -e '.streams | any(.codec_type == "video") and any(.codec_type == "audio")' "$STREAM_JSON" >/dev/null \
|
| 53 |
+
|| die "input must contain decodable video and audio streams"
|
| 54 |
+
|
| 55 |
+
WIDTH="$(jq -r '[.streams[] | select(.codec_type == "video")][0].width' "$STREAM_JSON")"
|
| 56 |
+
HEIGHT="$(jq -r '[.streams[] | select(.codec_type == "video")][0].height' "$STREAM_JSON")"
|
| 57 |
+
FPS="$(jq -r '[.streams[] | select(.codec_type == "video")][0].avg_frame_rate' "$STREAM_JSON")"
|
| 58 |
+
[[ "$FPS" != "0/0" && -n "$FPS" ]] || FPS="30"
|
| 59 |
+
|
| 60 |
+
MEASURE_LOG="$TMP_DIR/loudnorm-pass1.log"
|
| 61 |
+
ffmpeg -hide_banner -nostdin -nostats -i "$INPUT" \
|
| 62 |
+
-map 0:a:0 -vn \
|
| 63 |
+
-af 'loudnorm=I=-16:TP=-1.5:LRA=9:print_format=json' \
|
| 64 |
+
-f null - >/dev/null 2>"$MEASURE_LOG"
|
| 65 |
+
|
| 66 |
+
MEASURE_JSON="$TMP_DIR/measure.json"
|
| 67 |
+
sed -n '/^{/,/^}/p' "$MEASURE_LOG" >"$MEASURE_JSON"
|
| 68 |
+
jq -e . "$MEASURE_JSON" >/dev/null || die "could not parse loudness measurement"
|
| 69 |
+
|
| 70 |
+
MEASURED_I="$(jq -r .input_i "$MEASURE_JSON")"
|
| 71 |
+
MEASURED_TP="$(jq -r .input_tp "$MEASURE_JSON")"
|
| 72 |
+
MEASURED_LRA="$(jq -r .input_lra "$MEASURE_JSON")"
|
| 73 |
+
MEASURED_THRESH="$(jq -r .input_thresh "$MEASURE_JSON")"
|
| 74 |
+
OFFSET="$(jq -r .target_offset "$MEASURE_JSON")"
|
| 75 |
+
|
| 76 |
+
LOUDNORM="loudnorm=I=-16:TP=-1.5:LRA=9:measured_I=${MEASURED_I}:measured_TP=${MEASURED_TP}:measured_LRA=${MEASURED_LRA}:measured_thresh=${MEASURED_THRESH}:offset=${OFFSET}:linear=true:print_format=summary"
|
| 77 |
+
VIDEO_FILTER="scale=trunc(iw/2)*2:trunc(ih/2)*2:flags=lanczos,setsar=1,fps=${FPS},format=yuv420p"
|
| 78 |
+
|
| 79 |
+
encode() {
|
| 80 |
+
local crf="$1"
|
| 81 |
+
local preset="$2"
|
| 82 |
+
local audio_bitrate="$3"
|
| 83 |
+
local destination="$4"
|
| 84 |
+
local temporary="$5"
|
| 85 |
+
|
| 86 |
+
ffmpeg -hide_banner -nostdin -loglevel warning -stats -i "$INPUT" \
|
| 87 |
+
-map 0:v:0 -map 0:a:0 -sn -dn \
|
| 88 |
+
-vf "$VIDEO_FILTER" -af "$LOUDNORM" \
|
| 89 |
+
-c:v libx264 -preset "$preset" -crf "$crf" -profile:v high \
|
| 90 |
+
-pix_fmt yuv420p -tag:v avc1 -fps_mode cfr \
|
| 91 |
+
-color_primaries bt709 -color_trc bt709 -colorspace bt709 \
|
| 92 |
+
-c:a aac -b:a "$audio_bitrate" -ar 48000 -ac 2 \
|
| 93 |
+
-map_metadata -1 -map_chapters -1 -movflags +faststart \
|
| 94 |
+
"$temporary"
|
| 95 |
+
[[ -s "$temporary" ]] || die "encoder produced an empty output"
|
| 96 |
+
mv -- "$temporary" "$destination"
|
| 97 |
+
}
|
| 98 |
+
|
| 99 |
+
encode 16 slow 256k "$MASTER" "$TMP_DIR/master.mp4"
|
| 100 |
+
encode 24 medium 160k "$SHARE" "$TMP_DIR/share.mp4"
|
| 101 |
+
|
| 102 |
+
for file in "$MASTER" "$SHARE"; do
|
| 103 |
+
ffmpeg -hide_banner -nostdin -v error -xerror -i "$file" \
|
| 104 |
+
-map 0:v:0 -map 0:a:0 -f null - >/dev/null
|
| 105 |
+
done
|
| 106 |
+
|
| 107 |
+
ffprobe -v error -show_streams -show_format -of json "$MASTER" >"$TMP_DIR/master-probe.json"
|
| 108 |
+
ffprobe -v error -show_streams -show_format -of json "$SHARE" >"$TMP_DIR/share-probe.json"
|
| 109 |
+
|
| 110 |
+
for probe_file in "$STREAM_JSON" "$TMP_DIR/master-probe.json" "$TMP_DIR/share-probe.json"; do
|
| 111 |
+
jq 'if .format.filename? then .format.filename = (.format.filename | split("/") | last) else . end' \
|
| 112 |
+
"$probe_file" >"${probe_file}.portable"
|
| 113 |
+
mv -- "${probe_file}.portable" "$probe_file"
|
| 114 |
+
done
|
| 115 |
+
|
| 116 |
+
ffmpeg -hide_banner -nostdin -i "$MASTER" \
|
| 117 |
+
-vf 'blackdetect=d=0.10:pix_th=0.02' -an -f null - \
|
| 118 |
+
>/dev/null 2>"$TMP_DIR/blackdetect.log"
|
| 119 |
+
BLACK_EVENTS="$(grep -c 'black_start:' "$TMP_DIR/blackdetect.log" || true)"
|
| 120 |
+
|
| 121 |
+
DURATION="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$MASTER")"
|
| 122 |
+
awk -v duration="$DURATION" 'BEGIN {
|
| 123 |
+
p[1]=0.2; p[2]=duration*0.125; p[3]=duration*0.25; p[4]=duration*0.375;
|
| 124 |
+
p[5]=duration*0.5; p[6]=duration*0.625; p[7]=duration*0.75;
|
| 125 |
+
p[8]=duration*0.875; p[9]=duration-0.2;
|
| 126 |
+
for(i=1;i<=9;i++) printf "%.6f\n", p[i]
|
| 127 |
+
}' >"$TMP_DIR/timestamps.txt"
|
| 128 |
+
|
| 129 |
+
if (( WIDTH > HEIGHT )); then
|
| 130 |
+
CONTACT_FRAME_FILTER='scale=480:270:force_original_aspect_ratio=decrease:flags=lanczos,pad=480:270:(ow-iw)/2:(oh-ih)/2:color=black'
|
| 131 |
+
elif (( HEIGHT > WIDTH )); then
|
| 132 |
+
CONTACT_FRAME_FILTER='scale=270:480:force_original_aspect_ratio=decrease:flags=lanczos,pad=270:480:(ow-iw)/2:(oh-ih)/2:color=black'
|
| 133 |
+
else
|
| 134 |
+
CONTACT_FRAME_FILTER='scale=360:360:force_original_aspect_ratio=decrease:flags=lanczos,pad=360:360:(ow-iw)/2:(oh-ih)/2:color=black'
|
| 135 |
+
fi
|
| 136 |
+
|
| 137 |
+
index=0
|
| 138 |
+
while IFS= read -r timestamp; do
|
| 139 |
+
index=$((index + 1))
|
| 140 |
+
printf -v frame '%s/frame-%02d.png' "$TMP_DIR" "$index"
|
| 141 |
+
ffmpeg -hide_banner -nostdin -loglevel error -ss "$timestamp" -i "$MASTER" \
|
| 142 |
+
-frames:v 1 -vf "$CONTACT_FRAME_FILTER" -update 1 "$frame"
|
| 143 |
+
done <"$TMP_DIR/timestamps.txt"
|
| 144 |
+
|
| 145 |
+
ffmpeg -hide_banner -nostdin -loglevel error -framerate 1 -start_number 1 \
|
| 146 |
+
-i "$TMP_DIR/frame-%02d.png" -frames:v 1 \
|
| 147 |
+
-vf 'tile=3x3:padding=12:margin=12:color=0x101218' -update 1 "$TMP_DIR/contact.png"
|
| 148 |
+
mv -- "$TMP_DIR/contact.png" "$CONTACT"
|
| 149 |
+
|
| 150 |
+
jq -n \
|
| 151 |
+
--arg status verified \
|
| 152 |
+
--arg input "$INPUT_REPORT" \
|
| 153 |
+
--arg master "$MASTER_REPORT" \
|
| 154 |
+
--arg share "$SHARE_REPORT" \
|
| 155 |
+
--arg contact "$CONTACT_REPORT" \
|
| 156 |
+
--arg duration "$DURATION" \
|
| 157 |
+
--argjson black_events "$BLACK_EVENTS" \
|
| 158 |
+
--slurpfile measured "$MEASURE_JSON" \
|
| 159 |
+
--slurpfile source_probe "$STREAM_JSON" \
|
| 160 |
+
--slurpfile master_probe "$TMP_DIR/master-probe.json" \
|
| 161 |
+
--slurpfile share_probe "$TMP_DIR/share-probe.json" \
|
| 162 |
+
'{status:$status,input:$input,master:$master,share:$share,contact_sheet:$contact,duration_s:($duration|tonumber),source_loudness:$measured[0],source_probe:$source_probe[0],master_probe:$master_probe[0],share_probe:$share_probe[0],full_decode_passed:true,black_frame_events:$black_events}' \
|
| 163 |
+
>"$TMP_DIR/report.json"
|
| 164 |
+
mv -- "$TMP_DIR/report.json" "$REPORT"
|
| 165 |
+
|
| 166 |
+
printf 'Master: %s\nShare: %s\nReport: %s\nContact: %s\n' "$MASTER" "$SHARE" "$REPORT" "$CONTACT"
|
optional-skills/creative/ai-presenter-video/scripts/init_job.py
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
#!/usr/bin/env python3
|
| 2 |
+
"""Create a non-overwriting presenter-video job from minimal inputs."""
|
| 3 |
+
|
| 4 |
+
from __future__ import annotations
|
| 5 |
+
|
| 6 |
+
import argparse
|
| 7 |
+
import json
|
| 8 |
+
import re
|
| 9 |
+
import sys
|
| 10 |
+
from pathlib import Path
|
| 11 |
+
|
| 12 |
+
|
| 13 |
+
SKILL_DIR = Path(__file__).resolve().parent.parent
|
| 14 |
+
TEMPLATE = SKILL_DIR / "assets" / "job.template.json"
|
| 15 |
+
ASPECT_DEFAULTS = {
|
| 16 |
+
"9:16": (1080, 1920),
|
| 17 |
+
"16:9": (1920, 1080),
|
| 18 |
+
"1:1": (1080, 1080),
|
| 19 |
+
"4:5": (1080, 1350),
|
| 20 |
+
}
|
| 21 |
+
|
| 22 |
+
|
| 23 |
+
def absolute_existing(path_text: str, label: str) -> str:
|
| 24 |
+
path = Path(path_text).expanduser().resolve()
|
| 25 |
+
if not path.is_file():
|
| 26 |
+
raise ValueError(f"{label} does not exist or is not a file: {path}")
|
| 27 |
+
return str(path)
|
| 28 |
+
|
| 29 |
+
|
| 30 |
+
def slugify(value: str) -> str:
|
| 31 |
+
slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
|
| 32 |
+
return slug or "presenter-video"
|
| 33 |
+
|
| 34 |
+
|
| 35 |
+
def parse_args() -> argparse.Namespace:
|
| 36 |
+
parser = argparse.ArgumentParser(description=__doc__)
|
| 37 |
+
parser.add_argument("--job-dir", required=True)
|
| 38 |
+
parser.add_argument("--presenter-image", required=True)
|
| 39 |
+
source = parser.add_mutually_exclusive_group(required=True)
|
| 40 |
+
source.add_argument("--topic")
|
| 41 |
+
source.add_argument("--script", help="Existing local script file")
|
| 42 |
+
parser.add_argument("--voice-sample")
|
| 43 |
+
parser.add_argument("--supporting-media", action="append", default=[])
|
| 44 |
+
parser.add_argument("--language", default="auto")
|
| 45 |
+
parser.add_argument("--audience", default="general")
|
| 46 |
+
parser.add_argument("--duration", type=float, default=60.0)
|
| 47 |
+
parser.add_argument("--aspect", choices=sorted(ASPECT_DEFAULTS), default="9:16")
|
| 48 |
+
parser.add_argument("--width", type=int)
|
| 49 |
+
parser.add_argument("--height", type=int)
|
| 50 |
+
parser.add_argument("--fps", type=int, choices=(24, 25, 30, 50, 60), default=30)
|
| 51 |
+
parser.add_argument("--style", default="credible contemporary presenter")
|
| 52 |
+
parser.add_argument("--watermark", default="")
|
| 53 |
+
parser.add_argument("--cta", default="")
|
| 54 |
+
parser.add_argument("--rights-confirmed", action="store_true")
|
| 55 |
+
parser.add_argument("--adult-presenter-confirmed", action="store_true")
|
| 56 |
+
parser.add_argument("--remote-upload-approved", action="store_true")
|
| 57 |
+
parser.add_argument("--voice-clone-approved", action="store_true")
|
| 58 |
+
return parser.parse_args()
|
| 59 |
+
|
| 60 |
+
|
| 61 |
+
def main() -> int:
|
| 62 |
+
args = parse_args()
|
| 63 |
+
if not 5 <= args.duration <= 1800:
|
| 64 |
+
raise ValueError("--duration must be between 5 and 1800 seconds")
|
| 65 |
+
if (args.width is None) != (args.height is None):
|
| 66 |
+
raise ValueError("--width and --height must be supplied together")
|
| 67 |
+
|
| 68 |
+
width, height = ASPECT_DEFAULTS[args.aspect]
|
| 69 |
+
if args.width is not None and args.height is not None:
|
| 70 |
+
width, height = args.width, args.height
|
| 71 |
+
if min(width, height) < 256 or max(width, height) > 7680:
|
| 72 |
+
raise ValueError("custom dimensions must be between 256 and 7680 pixels")
|
| 73 |
+
|
| 74 |
+
job_dir = Path(args.job_dir).expanduser().resolve()
|
| 75 |
+
if job_dir.exists() and any(job_dir.iterdir()):
|
| 76 |
+
raise ValueError(f"job directory must be absent or empty: {job_dir}")
|
| 77 |
+
job_dir.mkdir(parents=True, exist_ok=True)
|
| 78 |
+
|
| 79 |
+
manifest = json.loads(TEMPLATE.read_text(encoding="utf-8"))
|
| 80 |
+
manifest["job_id"] = slugify(job_dir.name)
|
| 81 |
+
manifest["input"]["topic"] = (args.topic or "").strip()
|
| 82 |
+
manifest["input"]["script_path"] = (
|
| 83 |
+
absolute_existing(args.script, "script") if args.script else ""
|
| 84 |
+
)
|
| 85 |
+
manifest["input"]["presenter_image"] = absolute_existing(
|
| 86 |
+
args.presenter_image, "presenter image"
|
| 87 |
+
)
|
| 88 |
+
manifest["input"]["voice_sample"] = (
|
| 89 |
+
absolute_existing(args.voice_sample, "voice sample")
|
| 90 |
+
if args.voice_sample
|
| 91 |
+
else ""
|
| 92 |
+
)
|
| 93 |
+
manifest["input"]["supporting_media"] = [
|
| 94 |
+
absolute_existing(item, "supporting media") for item in args.supporting_media
|
| 95 |
+
]
|
| 96 |
+
manifest["input"]["rights_confirmed"] = args.rights_confirmed
|
| 97 |
+
manifest["input"]["adult_presenter_confirmed"] = args.adult_presenter_confirmed
|
| 98 |
+
manifest["input"]["remote_upload_approved"] = args.remote_upload_approved
|
| 99 |
+
manifest["input"]["voice_clone_approved"] = args.voice_clone_approved
|
| 100 |
+
|
| 101 |
+
creative = manifest["creative"]
|
| 102 |
+
creative.update(
|
| 103 |
+
{
|
| 104 |
+
"language": args.language,
|
| 105 |
+
"audience": args.audience,
|
| 106 |
+
"duration_target_s": args.duration,
|
| 107 |
+
"aspect": args.aspect,
|
| 108 |
+
"width": width,
|
| 109 |
+
"height": height,
|
| 110 |
+
"fps": args.fps,
|
| 111 |
+
"style": args.style,
|
| 112 |
+
"watermark": args.watermark,
|
| 113 |
+
"cta": args.cta,
|
| 114 |
+
}
|
| 115 |
+
)
|
| 116 |
+
|
| 117 |
+
directories = [
|
| 118 |
+
"docs",
|
| 119 |
+
"assets/source",
|
| 120 |
+
"assets/audio/reference",
|
| 121 |
+
"assets/audio/raw",
|
| 122 |
+
"assets/audio/final",
|
| 123 |
+
"assets/video/candidates",
|
| 124 |
+
"assets/video/selected",
|
| 125 |
+
"assets/video/render",
|
| 126 |
+
"assets/captions",
|
| 127 |
+
"qa/requests",
|
| 128 |
+
"qa/asr",
|
| 129 |
+
"qa/contacts",
|
| 130 |
+
"qa/reports",
|
| 131 |
+
"renders",
|
| 132 |
+
"outputs",
|
| 133 |
+
]
|
| 134 |
+
for relative in directories:
|
| 135 |
+
(job_dir / relative).mkdir(parents=True, exist_ok=True)
|
| 136 |
+
|
| 137 |
+
job_path = job_dir / "job.json"
|
| 138 |
+
job_path.write_text(
|
| 139 |
+
json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
|
| 140 |
+
encoding="utf-8",
|
| 141 |
+
)
|
| 142 |
+
print(json.dumps({"job": str(job_path), "state": "intake"}, ensure_ascii=False))
|
| 143 |
+
return 0
|
| 144 |
+
|
| 145 |
+
|
| 146 |
+
if __name__ == "__main__":
|
| 147 |
+
try:
|
| 148 |
+
raise SystemExit(main())
|
| 149 |
+
except ValueError as exc:
|
| 150 |
+
print(f"ERROR: {exc}", file=sys.stderr)
|
| 151 |
+
raise SystemExit(2)
|
optional-skills/creative/ai-presenter-video/scripts/preflight.py
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
#!/usr/bin/env python3
|
| 2 |
+
"""Validate a presenter-video job and write a machine-readable preflight report."""
|
| 3 |
+
|
| 4 |
+
from __future__ import annotations
|
| 5 |
+
|
| 6 |
+
import json
|
| 7 |
+
import shutil
|
| 8 |
+
import subprocess
|
| 9 |
+
import sys
|
| 10 |
+
from pathlib import Path
|
| 11 |
+
from typing import Any
|
| 12 |
+
|
| 13 |
+
|
| 14 |
+
def probe(path: Path) -> dict[str, Any]:
|
| 15 |
+
result = subprocess.run(
|
| 16 |
+
[
|
| 17 |
+
"ffprobe",
|
| 18 |
+
"-v",
|
| 19 |
+
"error",
|
| 20 |
+
"-show_entries",
|
| 21 |
+
"stream=index,codec_type,codec_name,width,height,pix_fmt,sample_rate,channels,r_frame_rate:format=duration,size,bit_rate",
|
| 22 |
+
"-of",
|
| 23 |
+
"json",
|
| 24 |
+
str(path),
|
| 25 |
+
],
|
| 26 |
+
check=True,
|
| 27 |
+
capture_output=True,
|
| 28 |
+
text=True,
|
| 29 |
+
)
|
| 30 |
+
return json.loads(result.stdout)
|
| 31 |
+
|
| 32 |
+
|
| 33 |
+
def require_file(value: str, label: str, errors: list[str]) -> Path | None:
|
| 34 |
+
if not value:
|
| 35 |
+
errors.append(f"missing {label}")
|
| 36 |
+
return None
|
| 37 |
+
path = Path(value).expanduser().resolve()
|
| 38 |
+
if not path.is_file():
|
| 39 |
+
errors.append(f"{label} is not a file: {path}")
|
| 40 |
+
return None
|
| 41 |
+
return path
|
| 42 |
+
|
| 43 |
+
|
| 44 |
+
def write_atomic(path: Path, text: str) -> None:
|
| 45 |
+
temporary = path.with_suffix(path.suffix + ".tmp")
|
| 46 |
+
temporary.write_text(text, encoding="utf-8")
|
| 47 |
+
temporary.replace(path)
|
| 48 |
+
|
| 49 |
+
|
| 50 |
+
def main() -> int:
|
| 51 |
+
if len(sys.argv) != 2:
|
| 52 |
+
print("Usage: preflight.py ~/Videos/my-presenter-video/job.json", file=sys.stderr)
|
| 53 |
+
return 64
|
| 54 |
+
if not shutil.which("ffprobe"):
|
| 55 |
+
print("ERROR: ffprobe is required", file=sys.stderr)
|
| 56 |
+
return 2
|
| 57 |
+
|
| 58 |
+
job_path = Path(sys.argv[1]).expanduser().resolve()
|
| 59 |
+
if not job_path.is_file():
|
| 60 |
+
print(f"ERROR: job manifest does not exist: {job_path}", file=sys.stderr)
|
| 61 |
+
return 2
|
| 62 |
+
job = json.loads(job_path.read_text(encoding="utf-8"))
|
| 63 |
+
job_dir = job_path.parent
|
| 64 |
+
errors: list[str] = []
|
| 65 |
+
remote_blockers: list[str] = []
|
| 66 |
+
warnings: list[str] = []
|
| 67 |
+
media: dict[str, Any] = {}
|
| 68 |
+
|
| 69 |
+
input_data = job.get("input", {})
|
| 70 |
+
topic = str(input_data.get("topic", "")).strip()
|
| 71 |
+
script_text = str(input_data.get("script_path", "")).strip()
|
| 72 |
+
if not topic and not script_text:
|
| 73 |
+
errors.append("topic or script_path is required")
|
| 74 |
+
if script_text:
|
| 75 |
+
require_file(script_text, "script", errors)
|
| 76 |
+
|
| 77 |
+
image = require_file(str(input_data.get("presenter_image", "")), "presenter image", errors)
|
| 78 |
+
if image:
|
| 79 |
+
try:
|
| 80 |
+
media["presenter_image"] = probe(image)
|
| 81 |
+
streams = [
|
| 82 |
+
stream
|
| 83 |
+
for stream in media["presenter_image"].get("streams", [])
|
| 84 |
+
if stream.get("codec_type") == "video"
|
| 85 |
+
]
|
| 86 |
+
if not streams:
|
| 87 |
+
errors.append("presenter image has no decodable image/video stream")
|
| 88 |
+
else:
|
| 89 |
+
width = int(streams[0].get("width") or 0)
|
| 90 |
+
height = int(streams[0].get("height") or 0)
|
| 91 |
+
if min(width, height) < 512:
|
| 92 |
+
warnings.append(f"presenter image is low resolution: {width}x{height}")
|
| 93 |
+
except (subprocess.CalledProcessError, json.JSONDecodeError) as exc:
|
| 94 |
+
errors.append(f"could not decode presenter image: {exc}")
|
| 95 |
+
|
| 96 |
+
voice_value = str(input_data.get("voice_sample", "")).strip()
|
| 97 |
+
if voice_value:
|
| 98 |
+
voice = require_file(voice_value, "voice sample", errors)
|
| 99 |
+
if voice:
|
| 100 |
+
try:
|
| 101 |
+
media["voice_sample"] = probe(voice)
|
| 102 |
+
streams = [
|
| 103 |
+
stream
|
| 104 |
+
for stream in media["voice_sample"].get("streams", [])
|
| 105 |
+
if stream.get("codec_type") == "audio"
|
| 106 |
+
]
|
| 107 |
+
if not streams:
|
| 108 |
+
errors.append("voice sample has no audio stream")
|
| 109 |
+
duration = float(media["voice_sample"].get("format", {}).get("duration") or 0)
|
| 110 |
+
if duration < 4:
|
| 111 |
+
warnings.append(f"voice sample is short: {duration:.3f}s")
|
| 112 |
+
if duration > 60:
|
| 113 |
+
warnings.append(f"voice sample is unusually long: {duration:.3f}s")
|
| 114 |
+
except (subprocess.CalledProcessError, json.JSONDecodeError, ValueError) as exc:
|
| 115 |
+
errors.append(f"could not decode voice sample: {exc}")
|
| 116 |
+
if not input_data.get("voice_clone_approved"):
|
| 117 |
+
remote_blockers.append("voice_clone_approved must be true before voice cloning")
|
| 118 |
+
else:
|
| 119 |
+
warnings.append("no voice sample supplied; use and record a stock voice")
|
| 120 |
+
|
| 121 |
+
supporting_reports = []
|
| 122 |
+
for value in input_data.get("supporting_media", []):
|
| 123 |
+
path = require_file(str(value), "supporting media", errors)
|
| 124 |
+
if path:
|
| 125 |
+
try:
|
| 126 |
+
supporting_reports.append({"file": path.name, "probe": probe(path)})
|
| 127 |
+
except (subprocess.CalledProcessError, json.JSONDecodeError) as exc:
|
| 128 |
+
errors.append(f"could not decode supporting media {path}: {exc}")
|
| 129 |
+
media["supporting_media"] = supporting_reports
|
| 130 |
+
|
| 131 |
+
if not input_data.get("rights_confirmed"):
|
| 132 |
+
remote_blockers.append("rights_confirmed must be true before presenter synthesis")
|
| 133 |
+
if not input_data.get("adult_presenter_confirmed"):
|
| 134 |
+
remote_blockers.append("adult_presenter_confirmed must be true before presenter synthesis")
|
| 135 |
+
if not input_data.get("remote_upload_approved"):
|
| 136 |
+
remote_blockers.append("remote_upload_approved must be true before remote generation")
|
| 137 |
+
|
| 138 |
+
manual = job.get("manual_input_review", {})
|
| 139 |
+
for key in ("image_viewed", "single_clear_face", "image_has_no_unwanted_text"):
|
| 140 |
+
if not manual.get(key):
|
| 141 |
+
errors.append(f"manual_input_review.{key} must be true")
|
| 142 |
+
if voice_value:
|
| 143 |
+
for key in ("voice_sample_listened", "single_clear_speaker"):
|
| 144 |
+
if not manual.get(key):
|
| 145 |
+
errors.append(f"manual_input_review.{key} must be true")
|
| 146 |
+
|
| 147 |
+
creative = job.get("creative", {})
|
| 148 |
+
duration = float(creative.get("duration_target_s") or 0)
|
| 149 |
+
if not 5 <= duration <= 1800:
|
| 150 |
+
errors.append("creative.duration_target_s must be between 5 and 1800")
|
| 151 |
+
width = int(creative.get("width") or 0)
|
| 152 |
+
height = int(creative.get("height") or 0)
|
| 153 |
+
if min(width, height) < 256 or max(width, height) > 7680:
|
| 154 |
+
errors.append("creative width/height must be between 256 and 7680")
|
| 155 |
+
if int(creative.get("fps") or 0) not in (24, 25, 30, 50, 60):
|
| 156 |
+
errors.append("creative.fps must be one of 24, 25, 30, 50, or 60")
|
| 157 |
+
|
| 158 |
+
report_path = job_dir / "qa" / "reports" / "preflight.json"
|
| 159 |
+
report_path.parent.mkdir(parents=True, exist_ok=True)
|
| 160 |
+
report = {
|
| 161 |
+
"ok": not errors,
|
| 162 |
+
"remote_ready": not errors and not remote_blockers,
|
| 163 |
+
"job": job_path.name,
|
| 164 |
+
"errors": errors,
|
| 165 |
+
"remote_blockers": remote_blockers,
|
| 166 |
+
"warnings": warnings,
|
| 167 |
+
"media": media,
|
| 168 |
+
}
|
| 169 |
+
write_atomic(report_path, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
|
| 170 |
+
job.setdefault("qa", {})["preflight_report"] = "qa/reports/preflight.json"
|
| 171 |
+
write_atomic(job_path, json.dumps(job, ensure_ascii=False, indent=2) + "\n")
|
| 172 |
+
print(json.dumps(report, ensure_ascii=False, indent=2))
|
| 173 |
+
return 0 if not errors else 1
|
| 174 |
+
|
| 175 |
+
|
| 176 |
+
if __name__ == "__main__":
|
| 177 |
+
raise SystemExit(main())
|
optional-skills/creative/archify/SKILL.md
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: archify
|
| 3 |
+
description: Validated interactive HTML diagrams, upstream-maintained.
|
| 4 |
+
version: 2.17.0
|
| 5 |
+
author: tt-a1i
|
| 6 |
+
license: MIT
|
| 7 |
+
platforms: [linux, macos, windows]
|
| 8 |
+
metadata:
|
| 9 |
+
hermes:
|
| 10 |
+
tags: [diagram, architecture, workflow, sequence, dataflow, state-machine, mermaid, html, svg]
|
| 11 |
+
category: creative
|
| 12 |
+
related_skills: [architecture-diagram, excalidraw, concept-diagrams]
|
| 13 |
+
upstream:
|
| 14 |
+
repo: tt-a1i/archify
|
| 15 |
+
path: archify
|
| 16 |
+
---
|
| 17 |
+
|
| 18 |
+
# Archify (upstream-maintained)
|
| 19 |
+
|
| 20 |
+
> **Catalog stub.** This entry is maintained upstream at
|
| 21 |
+
> [tt-a1i/archify](https://github.com/tt-a1i/archify): the project ships a
|
| 22 |
+
> self-contained skill directory (`archify/`) with the Node CLI, schemas,
|
| 23 |
+
> renderers, examples and references. `hermes skills install
|
| 24 |
+
> official/creative/archify` pulls the current tree live from that repo
|
| 25 |
+
> (quarantined and scanned like any hub install) — this directory holds only
|
| 26 |
+
> the catalog metadata, so the vendored copy can never go stale.
|
| 27 |
+
|
| 28 |
+
Archify turns a small typed JSON spec into a self-contained, explorable HTML
|
| 29 |
+
diagram: `architecture`, `workflow`, `sequence`, `dataflow` and `lifecycle`
|
| 30 |
+
(state machine) types, dark/light themes, pan/zoom, search, relationship
|
| 31 |
+
tracing, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. It accepts
|
| 32 |
+
plain-language requirements or pasted Mermaid (`flowchart`, `sequenceDiagram`,
|
| 33 |
+
`stateDiagram`) and can read repository evidence when the diagram must reflect
|
| 34 |
+
real code. Every candidate goes through a 9-check `validate` / `deliver`
|
| 35 |
+
receipt, so the output is verifiable rather than eyeballed.
|
| 36 |
+
|
| 37 |
+
## Prerequisites
|
| 38 |
+
|
| 39 |
+
- Node.js 18+ on `PATH` (`node bin/archify.mjs doctor` confirms the install;
|
| 40 |
+
no `npm install` is needed inside the skill package).
|
| 41 |
+
- Installs pull ~200 files (~8 MB, mostly upstream tests and examples) from
|
| 42 |
+
GitHub; the fetch is pinned to one tree SHA, recorded in the bundle metadata.
|
| 43 |
+
- Upstream's "Update awareness" step runs `scripts/check-update.mjs`, which
|
| 44 |
+
reads a release manifest from GitHub and only prints a notice — it never
|
| 45 |
+
downloads or installs anything. Skip it if outbound calls are unwanted.
|
| 46 |
+
|
| 47 |
+
After install, the bundled `architecture-diagram` skill remains the
|
| 48 |
+
zero-dependency fallback (it ports the same Cocoon AI lineage archify grew out
|
| 49 |
+
of); prefer archify when the user wants validated receipts, Mermaid conversion,
|
| 50 |
+
sequence/lifecycle types, or export beyond a single HTML file.
|
| 51 |
+
|
| 52 |
+
Full documentation: https://github.com/tt-a1i/archify#readme
|
optional-skills/creative/ascii-art/SKILL.md
ADDED
|
@@ -0,0 +1,322 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: ascii-art
|
| 3 |
+
description: "ASCII art: pyfiglet, cowsay, boxes, image-to-ascii."
|
| 4 |
+
version: 4.0.0
|
| 5 |
+
author: 0xbyt4, Hermes Agent
|
| 6 |
+
license: MIT
|
| 7 |
+
dependencies: []
|
| 8 |
+
platforms: [linux, macos, windows]
|
| 9 |
+
metadata:
|
| 10 |
+
hermes:
|
| 11 |
+
tags: [ASCII, Art, Banners, Creative, Unicode, Text-Art, pyfiglet, figlet, cowsay, boxes]
|
| 12 |
+
related_skills: [excalidraw]
|
| 13 |
+
|
| 14 |
+
---
|
| 15 |
+
|
| 16 |
+
# ASCII Art Skill
|
| 17 |
+
|
| 18 |
+
Multiple tools for different ASCII art needs. All tools are local CLI programs or free REST APIs — no API keys required.
|
| 19 |
+
|
| 20 |
+
## Tool 1: Text Banners (pyfiglet — local)
|
| 21 |
+
|
| 22 |
+
Render text as large ASCII art banners. 571 built-in fonts.
|
| 23 |
+
|
| 24 |
+
### Setup
|
| 25 |
+
|
| 26 |
+
```bash
|
| 27 |
+
pip install pyfiglet --break-system-packages -q
|
| 28 |
+
```
|
| 29 |
+
|
| 30 |
+
### Usage
|
| 31 |
+
|
| 32 |
+
```bash
|
| 33 |
+
python -m pyfiglet "YOUR TEXT" -f slant
|
| 34 |
+
python -m pyfiglet "TEXT" -f doom -w 80 # Set width
|
| 35 |
+
python -m pyfiglet --list_fonts # List all 571 fonts
|
| 36 |
+
```
|
| 37 |
+
|
| 38 |
+
### Recommended fonts
|
| 39 |
+
|
| 40 |
+
| Style | Font | Best for |
|
| 41 |
+
|-------|------|----------|
|
| 42 |
+
| Clean & modern | `slant` | Project names, headers |
|
| 43 |
+
| Bold & blocky | `doom` | Titles, logos |
|
| 44 |
+
| Big & readable | `big` | Banners |
|
| 45 |
+
| Classic banner | `banner3` | Wide displays |
|
| 46 |
+
| Compact | `small` | Subtitles |
|
| 47 |
+
| Cyberpunk | `cyberlarge` | Tech themes |
|
| 48 |
+
| 3D effect | `3-d` | Splash screens |
|
| 49 |
+
| Gothic | `gothic` | Dramatic text |
|
| 50 |
+
|
| 51 |
+
### Tips
|
| 52 |
+
|
| 53 |
+
- Preview 2-3 fonts and let the user pick their favorite
|
| 54 |
+
- Short text (1-8 chars) works best with detailed fonts like `doom` or `block`
|
| 55 |
+
- Long text works better with compact fonts like `small` or `mini`
|
| 56 |
+
|
| 57 |
+
## Tool 2: Text Banners (asciified API — remote, no install)
|
| 58 |
+
|
| 59 |
+
Free REST API that converts text to ASCII art. 250+ FIGlet fonts. Returns plain text directly — no parsing needed. Use this when pyfiglet is not installed or as a quick alternative.
|
| 60 |
+
|
| 61 |
+
### Usage (via terminal curl)
|
| 62 |
+
|
| 63 |
+
```bash
|
| 64 |
+
# Basic text banner (default font)
|
| 65 |
+
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello+World"
|
| 66 |
+
|
| 67 |
+
# With a specific font
|
| 68 |
+
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Slant"
|
| 69 |
+
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Doom"
|
| 70 |
+
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Star+Wars"
|
| 71 |
+
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=3-D"
|
| 72 |
+
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Banner3"
|
| 73 |
+
|
| 74 |
+
# List all available fonts (returns JSON array)
|
| 75 |
+
curl -s "https://asciified.thelicato.io/api/v2/fonts"
|
| 76 |
+
```
|
| 77 |
+
|
| 78 |
+
### Tips
|
| 79 |
+
|
| 80 |
+
- URL-encode spaces as `+` in the text parameter
|
| 81 |
+
- The response is plain text ASCII art — no JSON wrapping, ready to display
|
| 82 |
+
- Font names are case-sensitive; use the fonts endpoint to get exact names
|
| 83 |
+
- Works from any terminal with curl — no Python or pip needed
|
| 84 |
+
|
| 85 |
+
## Tool 3: Cowsay (Message Art)
|
| 86 |
+
|
| 87 |
+
Classic tool that wraps text in a speech bubble with an ASCII character.
|
| 88 |
+
|
| 89 |
+
### Setup
|
| 90 |
+
|
| 91 |
+
```bash
|
| 92 |
+
sudo apt install cowsay -y # Debian/Ubuntu
|
| 93 |
+
# brew install cowsay # macOS
|
| 94 |
+
```
|
| 95 |
+
|
| 96 |
+
### Usage
|
| 97 |
+
|
| 98 |
+
```bash
|
| 99 |
+
cowsay "Hello World"
|
| 100 |
+
cowsay -f tux "Linux rules" # Tux the penguin
|
| 101 |
+
cowsay -f dragon "Rawr!" # Dragon
|
| 102 |
+
cowsay -f stegosaurus "Roar!" # Stegosaurus
|
| 103 |
+
cowthink "Hmm..." # Thought bubble
|
| 104 |
+
cowsay -l # List all characters
|
| 105 |
+
```
|
| 106 |
+
|
| 107 |
+
### Available characters (50+)
|
| 108 |
+
|
| 109 |
+
`beavis.zen`, `bong`, `bunny`, `cheese`, `daemon`, `default`, `dragon`,
|
| 110 |
+
`dragon-and-cow`, `elephant`, `eyes`, `flaming-skull`, `ghostbusters`,
|
| 111 |
+
`hellokitty`, `kiss`, `kitty`, `koala`, `luke-koala`, `mech-and-cow`,
|
| 112 |
+
`meow`, `moofasa`, `moose`, `ren`, `sheep`, `skeleton`, `small`,
|
| 113 |
+
`stegosaurus`, `stimpy`, `supermilker`, `surgery`, `three-eyes`,
|
| 114 |
+
`turkey`, `turtle`, `tux`, `udder`, `vader`, `vader-koala`, `www`
|
| 115 |
+
|
| 116 |
+
### Eye/tongue modifiers
|
| 117 |
+
|
| 118 |
+
```bash
|
| 119 |
+
cowsay -b "Borg" # =_= eyes
|
| 120 |
+
cowsay -d "Dead" # x_x eyes
|
| 121 |
+
cowsay -g "Greedy" # $_$ eyes
|
| 122 |
+
cowsay -p "Paranoid" # @_@ eyes
|
| 123 |
+
cowsay -s "Stoned" # *_* eyes
|
| 124 |
+
cowsay -w "Wired" # O_O eyes
|
| 125 |
+
cowsay -e "OO" "Msg" # Custom eyes
|
| 126 |
+
cowsay -T "U " "Msg" # Custom tongue
|
| 127 |
+
```
|
| 128 |
+
|
| 129 |
+
## Tool 4: Boxes (Decorative Borders)
|
| 130 |
+
|
| 131 |
+
Draw decorative ASCII art borders/frames around any text. 70+ built-in designs.
|
| 132 |
+
|
| 133 |
+
### Setup
|
| 134 |
+
|
| 135 |
+
```bash
|
| 136 |
+
sudo apt install boxes -y # Debian/Ubuntu
|
| 137 |
+
# brew install boxes # macOS
|
| 138 |
+
```
|
| 139 |
+
|
| 140 |
+
### Usage
|
| 141 |
+
|
| 142 |
+
```bash
|
| 143 |
+
echo "Hello World" | boxes # Default box
|
| 144 |
+
echo "Hello World" | boxes -d stone # Stone border
|
| 145 |
+
echo "Hello World" | boxes -d parchment # Parchment scroll
|
| 146 |
+
echo "Hello World" | boxes -d cat # Cat border
|
| 147 |
+
echo "Hello World" | boxes -d dog # Dog border
|
| 148 |
+
echo "Hello World" | boxes -d unicornsay # Unicorn
|
| 149 |
+
echo "Hello World" | boxes -d diamonds # Diamond pattern
|
| 150 |
+
echo "Hello World" | boxes -d c-cmt # C-style comment
|
| 151 |
+
echo "Hello World" | boxes -d html-cmt # HTML comment
|
| 152 |
+
echo "Hello World" | boxes -a c # Center text
|
| 153 |
+
boxes -l # List all 70+ designs
|
| 154 |
+
```
|
| 155 |
+
|
| 156 |
+
### Combine with pyfiglet or asciified
|
| 157 |
+
|
| 158 |
+
```bash
|
| 159 |
+
python -m pyfiglet "HERMES" -f slant | boxes -d stone
|
| 160 |
+
# Or without pyfiglet installed:
|
| 161 |
+
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=HERMES&font=Slant" | boxes -d stone
|
| 162 |
+
```
|
| 163 |
+
|
| 164 |
+
## Tool 5: TOIlet (Colored Text Art)
|
| 165 |
+
|
| 166 |
+
Like pyfiglet but with ANSI color effects and visual filters. Great for terminal eye candy.
|
| 167 |
+
|
| 168 |
+
### Setup
|
| 169 |
+
|
| 170 |
+
```bash
|
| 171 |
+
sudo apt install toilet toilet-fonts -y # Debian/Ubuntu
|
| 172 |
+
# brew install toilet # macOS
|
| 173 |
+
```
|
| 174 |
+
|
| 175 |
+
### Usage
|
| 176 |
+
|
| 177 |
+
```bash
|
| 178 |
+
toilet "Hello World" # Basic text art
|
| 179 |
+
toilet -f bigmono12 "Hello" # Specific font
|
| 180 |
+
toilet --gay "Rainbow!" # Rainbow coloring
|
| 181 |
+
toilet --metal "Metal!" # Metallic effect
|
| 182 |
+
toilet -F border "Bordered" # Add border
|
| 183 |
+
toilet -F border --gay "Fancy!" # Combined effects
|
| 184 |
+
toilet -f pagga "Block" # Block-style font (unique to toilet)
|
| 185 |
+
toilet -F list # List available filters
|
| 186 |
+
```
|
| 187 |
+
|
| 188 |
+
### Filters
|
| 189 |
+
|
| 190 |
+
`crop`, `gay` (rainbow), `metal`, `flip`, `flop`, `180`, `left`, `right`, `border`
|
| 191 |
+
|
| 192 |
+
**Note**: toilet outputs ANSI escape codes for colors — works in terminals but may not render in all contexts (e.g., plain text files, some chat platforms).
|
| 193 |
+
|
| 194 |
+
## Tool 6: Image to ASCII Art
|
| 195 |
+
|
| 196 |
+
Convert images (PNG, JPEG, GIF, WEBP) to ASCII art.
|
| 197 |
+
|
| 198 |
+
### Option A: ascii-image-converter (recommended, modern)
|
| 199 |
+
|
| 200 |
+
```bash
|
| 201 |
+
# Install
|
| 202 |
+
sudo snap install ascii-image-converter
|
| 203 |
+
# OR: go install github.com/TheZoraiz/ascii-image-converter@latest
|
| 204 |
+
```
|
| 205 |
+
|
| 206 |
+
```bash
|
| 207 |
+
ascii-image-converter image.png # Basic
|
| 208 |
+
ascii-image-converter image.png -C # Color output
|
| 209 |
+
ascii-image-converter image.png -d 60,30 # Set dimensions
|
| 210 |
+
ascii-image-converter image.png -b # Braille characters
|
| 211 |
+
ascii-image-converter image.png -n # Negative/inverted
|
| 212 |
+
ascii-image-converter https://url/image.jpg # Direct URL
|
| 213 |
+
ascii-image-converter image.png --save-txt out # Save as text
|
| 214 |
+
```
|
| 215 |
+
|
| 216 |
+
### Option B: jp2a (lightweight, JPEG only)
|
| 217 |
+
|
| 218 |
+
```bash
|
| 219 |
+
sudo apt install jp2a -y
|
| 220 |
+
jp2a --width=80 image.jpg
|
| 221 |
+
jp2a --colors image.jpg # Colorized
|
| 222 |
+
```
|
| 223 |
+
|
| 224 |
+
## Tool 7: Search Pre-Made ASCII Art
|
| 225 |
+
|
| 226 |
+
Search curated ASCII art from the web. Use `terminal` with `curl`.
|
| 227 |
+
|
| 228 |
+
### Source A: ascii.co.uk (recommended for pre-made art)
|
| 229 |
+
|
| 230 |
+
Large collection of classic ASCII art organized by subject. Art is inside HTML `<pre>` tags. Fetch the page with curl, then extract art with a small Python snippet.
|
| 231 |
+
|
| 232 |
+
**URL pattern:** `https://ascii.co.uk/art/{subject}`
|
| 233 |
+
|
| 234 |
+
**Step 1 — Fetch the page:**
|
| 235 |
+
|
| 236 |
+
```bash
|
| 237 |
+
curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html
|
| 238 |
+
```
|
| 239 |
+
|
| 240 |
+
**Step 2 — Extract art from pre tags:**
|
| 241 |
+
|
| 242 |
+
```python
|
| 243 |
+
import re, html
|
| 244 |
+
with open('/tmp/ascii_art.html') as f:
|
| 245 |
+
text = f.read()
|
| 246 |
+
arts = re.findall(r'<pre[^>]*>(.*?)</pre>', text, re.DOTALL)
|
| 247 |
+
for art in arts:
|
| 248 |
+
clean = re.sub(r'<[^>]+>', '', art)
|
| 249 |
+
clean = html.unescape(clean).strip()
|
| 250 |
+
if len(clean) > 30:
|
| 251 |
+
print(clean)
|
| 252 |
+
print('\n---\n')
|
| 253 |
+
```
|
| 254 |
+
|
| 255 |
+
**Available subjects** (use as URL path):
|
| 256 |
+
- Animals: `cat`, `dog`, `horse`, `bird`, `fish`, `dragon`, `snake`, `rabbit`, `elephant`, `dolphin`, `butterfly`, `owl`, `wolf`, `bear`, `penguin`, `turtle`
|
| 257 |
+
- Objects: `car`, `ship`, `airplane`, `rocket`, `guitar`, `computer`, `coffee`, `beer`, `cake`, `house`, `castle`, `sword`, `crown`, `key`
|
| 258 |
+
- Nature: `tree`, `flower`, `sun`, `moon`, `star`, `mountain`, `ocean`, `rainbow`
|
| 259 |
+
- Characters: `skull`, `robot`, `angel`, `wizard`, `pirate`, `ninja`, `alien`
|
| 260 |
+
- Holidays: `christmas`, `halloween`, `valentine`
|
| 261 |
+
|
| 262 |
+
**Tips:**
|
| 263 |
+
- Preserve artist signatures/initials — important etiquette
|
| 264 |
+
- Multiple art pieces per page — pick the best one for the user
|
| 265 |
+
- Works reliably via curl, no JavaScript needed
|
| 266 |
+
|
| 267 |
+
### Source B: GitHub Octocat API (fun easter egg)
|
| 268 |
+
|
| 269 |
+
Returns a random GitHub Octocat with a wise quote. No auth needed.
|
| 270 |
+
|
| 271 |
+
```bash
|
| 272 |
+
curl -s https://api.github.com/octocat
|
| 273 |
+
```
|
| 274 |
+
|
| 275 |
+
## Tool 8: Fun ASCII Utilities (via curl)
|
| 276 |
+
|
| 277 |
+
These free services return ASCII art directly — great for fun extras.
|
| 278 |
+
|
| 279 |
+
### QR Codes as ASCII Art
|
| 280 |
+
|
| 281 |
+
```bash
|
| 282 |
+
curl -s "qrenco.de/Hello+World"
|
| 283 |
+
curl -s "qrenco.de/https://example.com"
|
| 284 |
+
```
|
| 285 |
+
|
| 286 |
+
### Weather as ASCII Art
|
| 287 |
+
|
| 288 |
+
```bash
|
| 289 |
+
curl -s "wttr.in/London" # Full weather report with ASCII graphics
|
| 290 |
+
curl -s "wttr.in/Moon" # Moon phase in ASCII art
|
| 291 |
+
curl -s "v2.wttr.in/London" # Detailed version
|
| 292 |
+
```
|
| 293 |
+
|
| 294 |
+
## Tool 9: LLM-Generated Custom Art (Fallback)
|
| 295 |
+
|
| 296 |
+
When tools above don't have what's needed, generate ASCII art directly using these Unicode characters:
|
| 297 |
+
|
| 298 |
+
### Character Palette
|
| 299 |
+
|
| 300 |
+
**Box Drawing:** `╔ ╗ ╚ ╝ ║ ═ ╠ ╣ ╦ ╩ ╬ ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯`
|
| 301 |
+
|
| 302 |
+
**Block Elements:** `░ ▒ ▓ █ ▄ ▀ ▌ ▐ ▖ ▗ ▘ ▝ ▚ ▞`
|
| 303 |
+
|
| 304 |
+
**Geometric & Symbols:** `◆ ◇ ◈ ● ○ ◉ ■ □ ▲ △ ▼ ▽ ★ ☆ ✦ ✧ ◀ ▶ ◁ ▷ ⬡ ⬢ ⌂`
|
| 305 |
+
|
| 306 |
+
### Rules
|
| 307 |
+
|
| 308 |
+
- Max width: 60 characters per line (terminal-safe)
|
| 309 |
+
- Max height: 15 lines for banners, 25 for scenes
|
| 310 |
+
- Monospace only: output must render correctly in fixed-width fonts
|
| 311 |
+
|
| 312 |
+
## Decision Flow
|
| 313 |
+
|
| 314 |
+
1. **Text as a banner** → pyfiglet if installed, otherwise asciified API via curl
|
| 315 |
+
2. **Wrap a message in fun character art** → cowsay
|
| 316 |
+
3. **Add decorative border/frame** → boxes (can combine with pyfiglet/asciified)
|
| 317 |
+
4. **Art of a specific thing** (cat, rocket, dragon) → ascii.co.uk via curl + parsing
|
| 318 |
+
5. **Convert an image to ASCII** → ascii-image-converter or jp2a
|
| 319 |
+
6. **QR code** → qrenco.de via curl
|
| 320 |
+
7. **Weather/moon art** → wttr.in via curl
|
| 321 |
+
8. **Something custom/creative** → LLM generation with Unicode palette
|
| 322 |
+
9. **Any tool not installed** → install it, or fall back to next option
|
optional-skills/creative/audiocraft-audio-generation/SKILL.md
ADDED
|
@@ -0,0 +1,569 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: audiocraft-audio-generation
|
| 3 |
+
description: "AudioCraft: MusicGen text-to-music, AudioGen text-to-sound."
|
| 4 |
+
version: 1.0.0
|
| 5 |
+
author: Orchestra Research
|
| 6 |
+
license: MIT
|
| 7 |
+
dependencies: [audiocraft, torch>=2.0.0, transformers>=4.30.0]
|
| 8 |
+
platforms: [linux, macos]
|
| 9 |
+
metadata:
|
| 10 |
+
hermes:
|
| 11 |
+
tags: [Multimodal, Audio Generation, Text-to-Music, Text-to-Audio, MusicGen]
|
| 12 |
+
related_skills: [heartmula, songwriting-and-ai-music]
|
| 13 |
+
|
| 14 |
+
---
|
| 15 |
+
|
| 16 |
+
# AudioCraft: Audio Generation
|
| 17 |
+
|
| 18 |
+
Guide to using Meta's AudioCraft for text-to-music and text-to-audio generation with MusicGen, AudioGen, and EnCodec.
|
| 19 |
+
|
| 20 |
+
## When to use AudioCraft
|
| 21 |
+
|
| 22 |
+
**Use AudioCraft when:**
|
| 23 |
+
- Need to generate music from text descriptions
|
| 24 |
+
- Creating sound effects and environmental audio
|
| 25 |
+
- Building music generation applications
|
| 26 |
+
- Need melody-conditioned music generation
|
| 27 |
+
- Want stereo audio output
|
| 28 |
+
- Require controllable music generation with style transfer
|
| 29 |
+
|
| 30 |
+
**Key features:**
|
| 31 |
+
- **MusicGen**: Text-to-music generation with melody conditioning
|
| 32 |
+
- **AudioGen**: Text-to-sound effects generation
|
| 33 |
+
- **EnCodec**: High-fidelity neural audio codec
|
| 34 |
+
- **Multiple model sizes**: Small (300M) to Large (3.3B)
|
| 35 |
+
- **Stereo support**: Full stereo audio generation
|
| 36 |
+
- **Style conditioning**: MusicGen-Style for reference-based generation
|
| 37 |
+
|
| 38 |
+
**Use alternatives instead:**
|
| 39 |
+
- **Stable Audio**: For longer commercial music generation
|
| 40 |
+
- **Bark**: For text-to-speech with music/sound effects
|
| 41 |
+
- **Riffusion**: For spectogram-based music generation
|
| 42 |
+
- **OpenAI Jukebox**: For raw audio generation with lyrics
|
| 43 |
+
|
| 44 |
+
## Quick start
|
| 45 |
+
|
| 46 |
+
### Installation
|
| 47 |
+
|
| 48 |
+
```bash
|
| 49 |
+
# From PyPI
|
| 50 |
+
pip install audiocraft
|
| 51 |
+
|
| 52 |
+
# From GitHub (latest)
|
| 53 |
+
pip install git+https://github.com/facebookresearch/audiocraft.git
|
| 54 |
+
|
| 55 |
+
# Or use HuggingFace Transformers
|
| 56 |
+
pip install transformers torch torchaudio
|
| 57 |
+
```
|
| 58 |
+
|
| 59 |
+
### Basic text-to-music (AudioCraft)
|
| 60 |
+
|
| 61 |
+
```python
|
| 62 |
+
import torchaudio
|
| 63 |
+
from audiocraft.models import MusicGen
|
| 64 |
+
|
| 65 |
+
# Load model
|
| 66 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 67 |
+
|
| 68 |
+
# Set generation parameters
|
| 69 |
+
model.set_generation_params(
|
| 70 |
+
duration=8, # seconds
|
| 71 |
+
top_k=250,
|
| 72 |
+
temperature=1.0
|
| 73 |
+
)
|
| 74 |
+
|
| 75 |
+
# Generate from text
|
| 76 |
+
descriptions = ["happy upbeat electronic dance music with synths"]
|
| 77 |
+
wav = model.generate(descriptions)
|
| 78 |
+
|
| 79 |
+
# Save audio
|
| 80 |
+
torchaudio.save("output.wav", wav[0].cpu(), sample_rate=32000)
|
| 81 |
+
```
|
| 82 |
+
|
| 83 |
+
### Using HuggingFace Transformers
|
| 84 |
+
|
| 85 |
+
```python
|
| 86 |
+
from transformers import AutoProcessor, MusicgenForConditionalGeneration
|
| 87 |
+
import scipy
|
| 88 |
+
|
| 89 |
+
# Load model and processor
|
| 90 |
+
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
|
| 91 |
+
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
|
| 92 |
+
model.to("cuda")
|
| 93 |
+
|
| 94 |
+
# Generate music
|
| 95 |
+
inputs = processor(
|
| 96 |
+
text=["80s pop track with bassy drums and synth"],
|
| 97 |
+
padding=True,
|
| 98 |
+
return_tensors="pt"
|
| 99 |
+
).to("cuda")
|
| 100 |
+
|
| 101 |
+
audio_values = model.generate(
|
| 102 |
+
**inputs,
|
| 103 |
+
do_sample=True,
|
| 104 |
+
guidance_scale=3,
|
| 105 |
+
max_new_tokens=256
|
| 106 |
+
)
|
| 107 |
+
|
| 108 |
+
# Save
|
| 109 |
+
sampling_rate = model.config.audio_encoder.sampling_rate
|
| 110 |
+
scipy.io.wavfile.write("output.wav", rate=sampling_rate, data=audio_values[0, 0].cpu().numpy())
|
| 111 |
+
```
|
| 112 |
+
|
| 113 |
+
### Text-to-sound with AudioGen
|
| 114 |
+
|
| 115 |
+
```python
|
| 116 |
+
from audiocraft.models import AudioGen
|
| 117 |
+
|
| 118 |
+
# Load AudioGen
|
| 119 |
+
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
| 120 |
+
|
| 121 |
+
model.set_generation_params(duration=5)
|
| 122 |
+
|
| 123 |
+
# Generate sound effects
|
| 124 |
+
descriptions = ["dog barking in a park with birds chirping"]
|
| 125 |
+
wav = model.generate(descriptions)
|
| 126 |
+
|
| 127 |
+
torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000)
|
| 128 |
+
```
|
| 129 |
+
|
| 130 |
+
## Core concepts
|
| 131 |
+
|
| 132 |
+
### Architecture overview
|
| 133 |
+
|
| 134 |
+
```
|
| 135 |
+
AudioCraft Architecture:
|
| 136 |
+
┌──────────────────────────────────────────────────────────────┐
|
| 137 |
+
│ Text Encoder (T5) │
|
| 138 |
+
│ │ │
|
| 139 |
+
│ Text Embeddings │
|
| 140 |
+
└────────────────────────┬─────────────────────────────────────┘
|
| 141 |
+
│
|
| 142 |
+
┌────────────────────────▼─────────────────────────────────────┐
|
| 143 |
+
│ Transformer Decoder (LM) │
|
| 144 |
+
│ Auto-regressively generates audio tokens │
|
| 145 |
+
│ Using efficient token interleaving patterns │
|
| 146 |
+
└────────────────────────┬─────────────────────────────────────┘
|
| 147 |
+
│
|
| 148 |
+
┌────────────────────────▼─────────────────────────────────────┐
|
| 149 |
+
│ EnCodec Audio Decoder │
|
| 150 |
+
│ Converts tokens back to audio waveform │
|
| 151 |
+
└──────────────────────────────────────────────────────────────┘
|
| 152 |
+
```
|
| 153 |
+
|
| 154 |
+
### Model variants
|
| 155 |
+
|
| 156 |
+
| Model | Size | Description | Use Case |
|
| 157 |
+
|-------|------|-------------|----------|
|
| 158 |
+
| `musicgen-small` | 300M | Text-to-music | Quick generation |
|
| 159 |
+
| `musicgen-medium` | 1.5B | Text-to-music | Balanced |
|
| 160 |
+
| `musicgen-large` | 3.3B | Text-to-music | Best quality |
|
| 161 |
+
| `musicgen-melody` | 1.5B | Text + melody | Melody conditioning |
|
| 162 |
+
| `musicgen-melody-large` | 3.3B | Text + melody | Best melody |
|
| 163 |
+
| `musicgen-stereo-*` | Varies | Stereo output | Stereo generation |
|
| 164 |
+
| `musicgen-style` | 1.5B | Style transfer | Reference-based |
|
| 165 |
+
| `audiogen-medium` | 1.5B | Text-to-sound | Sound effects |
|
| 166 |
+
|
| 167 |
+
### Generation parameters
|
| 168 |
+
|
| 169 |
+
| Parameter | Default | Description |
|
| 170 |
+
|-----------|---------|-------------|
|
| 171 |
+
| `duration` | 8.0 | Length in seconds (1-120) |
|
| 172 |
+
| `top_k` | 250 | Top-k sampling |
|
| 173 |
+
| `top_p` | 0.0 | Nucleus sampling (0 = disabled) |
|
| 174 |
+
| `temperature` | 1.0 | Sampling temperature |
|
| 175 |
+
| `cfg_coef` | 3.0 | Classifier-free guidance |
|
| 176 |
+
|
| 177 |
+
## MusicGen usage
|
| 178 |
+
|
| 179 |
+
### Text-to-music generation
|
| 180 |
+
|
| 181 |
+
```python
|
| 182 |
+
from audiocraft.models import MusicGen
|
| 183 |
+
import torchaudio
|
| 184 |
+
|
| 185 |
+
model = MusicGen.get_pretrained('facebook/musicgen-medium')
|
| 186 |
+
|
| 187 |
+
# Configure generation
|
| 188 |
+
model.set_generation_params(
|
| 189 |
+
duration=30, # Up to 30 seconds
|
| 190 |
+
top_k=250, # Sampling diversity
|
| 191 |
+
top_p=0.0, # 0 = use top_k only
|
| 192 |
+
temperature=1.0, # Creativity (higher = more varied)
|
| 193 |
+
cfg_coef=3.0 # Text adherence (higher = stricter)
|
| 194 |
+
)
|
| 195 |
+
|
| 196 |
+
# Generate multiple samples
|
| 197 |
+
descriptions = [
|
| 198 |
+
"epic orchestral soundtrack with strings and brass",
|
| 199 |
+
"chill lo-fi hip hop beat with jazzy piano",
|
| 200 |
+
"energetic rock song with electric guitar"
|
| 201 |
+
]
|
| 202 |
+
|
| 203 |
+
# Generate (returns [batch, channels, samples])
|
| 204 |
+
wav = model.generate(descriptions)
|
| 205 |
+
|
| 206 |
+
# Save each
|
| 207 |
+
for i, audio in enumerate(wav):
|
| 208 |
+
torchaudio.save(f"music_{i}.wav", audio.cpu(), sample_rate=32000)
|
| 209 |
+
```
|
| 210 |
+
|
| 211 |
+
### Melody-conditioned generation
|
| 212 |
+
|
| 213 |
+
```python
|
| 214 |
+
from audiocraft.models import MusicGen
|
| 215 |
+
import torchaudio
|
| 216 |
+
|
| 217 |
+
# Load melody model
|
| 218 |
+
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
| 219 |
+
model.set_generation_params(duration=30)
|
| 220 |
+
|
| 221 |
+
# Load melody audio
|
| 222 |
+
melody, sr = torchaudio.load("melody.wav")
|
| 223 |
+
|
| 224 |
+
# Generate with melody conditioning
|
| 225 |
+
descriptions = ["acoustic guitar folk song"]
|
| 226 |
+
wav = model.generate_with_chroma(descriptions, melody, sr)
|
| 227 |
+
|
| 228 |
+
torchaudio.save("melody_conditioned.wav", wav[0].cpu(), sample_rate=32000)
|
| 229 |
+
```
|
| 230 |
+
|
| 231 |
+
### Stereo generation
|
| 232 |
+
|
| 233 |
+
```python
|
| 234 |
+
from audiocraft.models import MusicGen
|
| 235 |
+
|
| 236 |
+
# Load stereo model
|
| 237 |
+
model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
|
| 238 |
+
model.set_generation_params(duration=15)
|
| 239 |
+
|
| 240 |
+
descriptions = ["ambient electronic music with wide stereo panning"]
|
| 241 |
+
wav = model.generate(descriptions)
|
| 242 |
+
|
| 243 |
+
# wav shape: [batch, 2, samples] for stereo
|
| 244 |
+
print(f"Stereo shape: {wav.shape}") # [1, 2, 480000]
|
| 245 |
+
torchaudio.save("stereo.wav", wav[0].cpu(), sample_rate=32000)
|
| 246 |
+
```
|
| 247 |
+
|
| 248 |
+
### Audio continuation
|
| 249 |
+
|
| 250 |
+
```python
|
| 251 |
+
from transformers import AutoProcessor, MusicgenForConditionalGeneration
|
| 252 |
+
|
| 253 |
+
processor = AutoProcessor.from_pretrained("facebook/musicgen-medium")
|
| 254 |
+
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-medium")
|
| 255 |
+
|
| 256 |
+
# Load audio to continue
|
| 257 |
+
import torchaudio
|
| 258 |
+
audio, sr = torchaudio.load("intro.wav")
|
| 259 |
+
|
| 260 |
+
# Process with text and audio
|
| 261 |
+
inputs = processor(
|
| 262 |
+
audio=audio.squeeze().numpy(),
|
| 263 |
+
sampling_rate=sr,
|
| 264 |
+
text=["continue with a epic chorus"],
|
| 265 |
+
padding=True,
|
| 266 |
+
return_tensors="pt"
|
| 267 |
+
)
|
| 268 |
+
|
| 269 |
+
# Generate continuation
|
| 270 |
+
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=512)
|
| 271 |
+
```
|
| 272 |
+
|
| 273 |
+
## MusicGen-Style usage
|
| 274 |
+
|
| 275 |
+
### Style-conditioned generation
|
| 276 |
+
|
| 277 |
+
```python
|
| 278 |
+
from audiocraft.models import MusicGen
|
| 279 |
+
|
| 280 |
+
# Load style model
|
| 281 |
+
model = MusicGen.get_pretrained('facebook/musicgen-style')
|
| 282 |
+
|
| 283 |
+
# Configure generation with style
|
| 284 |
+
model.set_generation_params(
|
| 285 |
+
duration=30,
|
| 286 |
+
cfg_coef=3.0,
|
| 287 |
+
cfg_coef_beta=5.0 # Style influence
|
| 288 |
+
)
|
| 289 |
+
|
| 290 |
+
# Configure style conditioner
|
| 291 |
+
model.set_style_conditioner_params(
|
| 292 |
+
eval_q=3, # RVQ quantizers (1-6)
|
| 293 |
+
excerpt_length=3.0 # Style excerpt length
|
| 294 |
+
)
|
| 295 |
+
|
| 296 |
+
# Load style reference
|
| 297 |
+
style_audio, sr = torchaudio.load("reference_style.wav")
|
| 298 |
+
|
| 299 |
+
# Generate with text + style
|
| 300 |
+
descriptions = ["upbeat dance track"]
|
| 301 |
+
wav = model.generate_with_style(descriptions, style_audio, sr)
|
| 302 |
+
```
|
| 303 |
+
|
| 304 |
+
### Style-only generation (no text)
|
| 305 |
+
|
| 306 |
+
```python
|
| 307 |
+
# Generate matching style without text prompt
|
| 308 |
+
model.set_generation_params(
|
| 309 |
+
duration=30,
|
| 310 |
+
cfg_coef=3.0,
|
| 311 |
+
cfg_coef_beta=None # Disable double CFG for style-only
|
| 312 |
+
)
|
| 313 |
+
|
| 314 |
+
wav = model.generate_with_style([None], style_audio, sr)
|
| 315 |
+
```
|
| 316 |
+
|
| 317 |
+
## AudioGen usage
|
| 318 |
+
|
| 319 |
+
### Sound effect generation
|
| 320 |
+
|
| 321 |
+
```python
|
| 322 |
+
from audiocraft.models import AudioGen
|
| 323 |
+
import torchaudio
|
| 324 |
+
|
| 325 |
+
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
| 326 |
+
model.set_generation_params(duration=10)
|
| 327 |
+
|
| 328 |
+
# Generate various sounds
|
| 329 |
+
descriptions = [
|
| 330 |
+
"thunderstorm with heavy rain and lightning",
|
| 331 |
+
"busy city traffic with car horns",
|
| 332 |
+
"ocean waves crashing on rocks",
|
| 333 |
+
"crackling campfire in forest"
|
| 334 |
+
]
|
| 335 |
+
|
| 336 |
+
wav = model.generate(descriptions)
|
| 337 |
+
|
| 338 |
+
for i, audio in enumerate(wav):
|
| 339 |
+
torchaudio.save(f"sound_{i}.wav", audio.cpu(), sample_rate=16000)
|
| 340 |
+
```
|
| 341 |
+
|
| 342 |
+
## EnCodec usage
|
| 343 |
+
|
| 344 |
+
### Audio compression
|
| 345 |
+
|
| 346 |
+
```python
|
| 347 |
+
from audiocraft.models import CompressionModel
|
| 348 |
+
import torch
|
| 349 |
+
import torchaudio
|
| 350 |
+
|
| 351 |
+
# Load EnCodec
|
| 352 |
+
model = CompressionModel.get_pretrained('facebook/encodec_32khz')
|
| 353 |
+
|
| 354 |
+
# Load audio
|
| 355 |
+
wav, sr = torchaudio.load("audio.wav")
|
| 356 |
+
|
| 357 |
+
# Ensure correct sample rate
|
| 358 |
+
if sr != 32000:
|
| 359 |
+
resampler = torchaudio.transforms.Resample(sr, 32000)
|
| 360 |
+
wav = resampler(wav)
|
| 361 |
+
|
| 362 |
+
# Encode to tokens
|
| 363 |
+
with torch.no_grad():
|
| 364 |
+
encoded = model.encode(wav.unsqueeze(0))
|
| 365 |
+
codes = encoded[0] # Audio codes
|
| 366 |
+
|
| 367 |
+
# Decode back to audio
|
| 368 |
+
with torch.no_grad():
|
| 369 |
+
decoded = model.decode(codes)
|
| 370 |
+
|
| 371 |
+
torchaudio.save("reconstructed.wav", decoded[0].cpu(), sample_rate=32000)
|
| 372 |
+
```
|
| 373 |
+
|
| 374 |
+
## Common workflows
|
| 375 |
+
|
| 376 |
+
### Workflow 1: Music generation pipeline
|
| 377 |
+
|
| 378 |
+
```python
|
| 379 |
+
import torch
|
| 380 |
+
import torchaudio
|
| 381 |
+
from audiocraft.models import MusicGen
|
| 382 |
+
|
| 383 |
+
class MusicGenerator:
|
| 384 |
+
def __init__(self, model_name="facebook/musicgen-medium"):
|
| 385 |
+
self.model = MusicGen.get_pretrained(model_name)
|
| 386 |
+
self.sample_rate = 32000
|
| 387 |
+
|
| 388 |
+
def generate(self, prompt, duration=30, temperature=1.0, cfg=3.0):
|
| 389 |
+
self.model.set_generation_params(
|
| 390 |
+
duration=duration,
|
| 391 |
+
top_k=250,
|
| 392 |
+
temperature=temperature,
|
| 393 |
+
cfg_coef=cfg
|
| 394 |
+
)
|
| 395 |
+
|
| 396 |
+
with torch.no_grad():
|
| 397 |
+
wav = self.model.generate([prompt])
|
| 398 |
+
|
| 399 |
+
return wav[0].cpu()
|
| 400 |
+
|
| 401 |
+
def generate_batch(self, prompts, duration=30):
|
| 402 |
+
self.model.set_generation_params(duration=duration)
|
| 403 |
+
|
| 404 |
+
with torch.no_grad():
|
| 405 |
+
wav = self.model.generate(prompts)
|
| 406 |
+
|
| 407 |
+
return wav.cpu()
|
| 408 |
+
|
| 409 |
+
def save(self, audio, path):
|
| 410 |
+
torchaudio.save(path, audio, sample_rate=self.sample_rate)
|
| 411 |
+
|
| 412 |
+
# Usage
|
| 413 |
+
generator = MusicGenerator()
|
| 414 |
+
audio = generator.generate(
|
| 415 |
+
"epic cinematic orchestral music",
|
| 416 |
+
duration=30,
|
| 417 |
+
temperature=1.0
|
| 418 |
+
)
|
| 419 |
+
generator.save(audio, "epic_music.wav")
|
| 420 |
+
```
|
| 421 |
+
|
| 422 |
+
### Workflow 2: Sound design batch processing
|
| 423 |
+
|
| 424 |
+
```python
|
| 425 |
+
import json
|
| 426 |
+
from pathlib import Path
|
| 427 |
+
from audiocraft.models import AudioGen
|
| 428 |
+
import torchaudio
|
| 429 |
+
|
| 430 |
+
def batch_generate_sounds(sound_specs, output_dir):
|
| 431 |
+
"""
|
| 432 |
+
Generate multiple sounds from specifications.
|
| 433 |
+
|
| 434 |
+
Args:
|
| 435 |
+
sound_specs: list of {"name": str, "description": str, "duration": float}
|
| 436 |
+
output_dir: output directory path
|
| 437 |
+
"""
|
| 438 |
+
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
| 439 |
+
output_dir = Path(output_dir)
|
| 440 |
+
output_dir.mkdir(exist_ok=True)
|
| 441 |
+
|
| 442 |
+
results = []
|
| 443 |
+
|
| 444 |
+
for spec in sound_specs:
|
| 445 |
+
model.set_generation_params(duration=spec.get("duration", 5))
|
| 446 |
+
|
| 447 |
+
wav = model.generate([spec["description"]])
|
| 448 |
+
|
| 449 |
+
output_path = output_dir / f"{spec['name']}.wav"
|
| 450 |
+
torchaudio.save(str(output_path), wav[0].cpu(), sample_rate=16000)
|
| 451 |
+
|
| 452 |
+
results.append({
|
| 453 |
+
"name": spec["name"],
|
| 454 |
+
"path": str(output_path),
|
| 455 |
+
"description": spec["description"]
|
| 456 |
+
})
|
| 457 |
+
|
| 458 |
+
return results
|
| 459 |
+
|
| 460 |
+
# Usage
|
| 461 |
+
sounds = [
|
| 462 |
+
{"name": "explosion", "description": "massive explosion with debris", "duration": 3},
|
| 463 |
+
{"name": "footsteps", "description": "footsteps on wooden floor", "duration": 5},
|
| 464 |
+
{"name": "door", "description": "wooden door creaking and closing", "duration": 2}
|
| 465 |
+
]
|
| 466 |
+
|
| 467 |
+
results = batch_generate_sounds(sounds, "sound_effects/")
|
| 468 |
+
```
|
| 469 |
+
|
| 470 |
+
### Workflow 3: Gradio demo
|
| 471 |
+
|
| 472 |
+
```python
|
| 473 |
+
import gradio as gr
|
| 474 |
+
import torch
|
| 475 |
+
import torchaudio
|
| 476 |
+
from audiocraft.models import MusicGen
|
| 477 |
+
|
| 478 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 479 |
+
|
| 480 |
+
def generate_music(prompt, duration, temperature, cfg_coef):
|
| 481 |
+
model.set_generation_params(
|
| 482 |
+
duration=duration,
|
| 483 |
+
temperature=temperature,
|
| 484 |
+
cfg_coef=cfg_coef
|
| 485 |
+
)
|
| 486 |
+
|
| 487 |
+
with torch.no_grad():
|
| 488 |
+
wav = model.generate([prompt])
|
| 489 |
+
|
| 490 |
+
# Save to temp file
|
| 491 |
+
path = "temp_output.wav"
|
| 492 |
+
torchaudio.save(path, wav[0].cpu(), sample_rate=32000)
|
| 493 |
+
return path
|
| 494 |
+
|
| 495 |
+
demo = gr.Interface(
|
| 496 |
+
fn=generate_music,
|
| 497 |
+
inputs=[
|
| 498 |
+
gr.Textbox(label="Music Description", placeholder="upbeat electronic dance music"),
|
| 499 |
+
gr.Slider(1, 30, value=8, label="Duration (seconds)"),
|
| 500 |
+
gr.Slider(0.5, 2.0, value=1.0, label="Temperature"),
|
| 501 |
+
gr.Slider(1.0, 10.0, value=3.0, label="CFG Coefficient")
|
| 502 |
+
],
|
| 503 |
+
outputs=gr.Audio(label="Generated Music"),
|
| 504 |
+
title="MusicGen Demo"
|
| 505 |
+
)
|
| 506 |
+
|
| 507 |
+
demo.launch()
|
| 508 |
+
```
|
| 509 |
+
|
| 510 |
+
## Performance optimization
|
| 511 |
+
|
| 512 |
+
### Memory optimization
|
| 513 |
+
|
| 514 |
+
```python
|
| 515 |
+
# Use smaller model
|
| 516 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 517 |
+
|
| 518 |
+
# Clear cache between generations
|
| 519 |
+
torch.cuda.empty_cache()
|
| 520 |
+
|
| 521 |
+
# Generate shorter durations
|
| 522 |
+
model.set_generation_params(duration=10) # Instead of 30
|
| 523 |
+
|
| 524 |
+
# Use half precision
|
| 525 |
+
model = model.half()
|
| 526 |
+
```
|
| 527 |
+
|
| 528 |
+
### Batch processing efficiency
|
| 529 |
+
|
| 530 |
+
```python
|
| 531 |
+
# Process multiple prompts at once (more efficient)
|
| 532 |
+
descriptions = ["prompt1", "prompt2", "prompt3", "prompt4"]
|
| 533 |
+
wav = model.generate(descriptions) # Single batch
|
| 534 |
+
|
| 535 |
+
# Instead of
|
| 536 |
+
for desc in descriptions:
|
| 537 |
+
wav = model.generate([desc]) # Multiple batches (slower)
|
| 538 |
+
```
|
| 539 |
+
|
| 540 |
+
### GPU memory requirements
|
| 541 |
+
|
| 542 |
+
| Model | FP32 VRAM | FP16 VRAM |
|
| 543 |
+
|-------|-----------|-----------|
|
| 544 |
+
| musicgen-small | ~4GB | ~2GB |
|
| 545 |
+
| musicgen-medium | ~8GB | ~4GB |
|
| 546 |
+
| musicgen-large | ~16GB | ~8GB |
|
| 547 |
+
|
| 548 |
+
## Common issues
|
| 549 |
+
|
| 550 |
+
| Issue | Solution |
|
| 551 |
+
|-------|----------|
|
| 552 |
+
| CUDA OOM | Use smaller model, reduce duration |
|
| 553 |
+
| Poor quality | Increase cfg_coef, better prompts |
|
| 554 |
+
| Generation too short | Check max duration setting |
|
| 555 |
+
| Audio artifacts | Try different temperature |
|
| 556 |
+
| Stereo not working | Use stereo model variant |
|
| 557 |
+
|
| 558 |
+
## References
|
| 559 |
+
|
| 560 |
+
- **[Advanced Usage](references/advanced-usage.md)** - Training, fine-tuning, deployment
|
| 561 |
+
- **[Troubleshooting](references/troubleshooting.md)** - Common issues and solutions
|
| 562 |
+
|
| 563 |
+
## Resources
|
| 564 |
+
|
| 565 |
+
- **GitHub**: https://github.com/facebookresearch/audiocraft
|
| 566 |
+
- **Paper (MusicGen)**: https://arxiv.org/abs/2306.05284
|
| 567 |
+
- **Paper (AudioGen)**: https://arxiv.org/abs/2209.15352
|
| 568 |
+
- **HuggingFace**: https://huggingface.co/facebook/musicgen-small
|
| 569 |
+
- **Demo**: https://huggingface.co/spaces/facebook/MusicGen
|
optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md
ADDED
|
@@ -0,0 +1,666 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# AudioCraft Advanced Usage Guide
|
| 2 |
+
|
| 3 |
+
## Fine-tuning MusicGen
|
| 4 |
+
|
| 5 |
+
### Custom dataset preparation
|
| 6 |
+
|
| 7 |
+
```python
|
| 8 |
+
import os
|
| 9 |
+
import json
|
| 10 |
+
from pathlib import Path
|
| 11 |
+
import torchaudio
|
| 12 |
+
|
| 13 |
+
def prepare_dataset(audio_dir, output_dir, metadata_file):
|
| 14 |
+
"""
|
| 15 |
+
Prepare dataset for MusicGen fine-tuning.
|
| 16 |
+
|
| 17 |
+
Directory structure:
|
| 18 |
+
output_dir/
|
| 19 |
+
├── audio/
|
| 20 |
+
│ ├── 0001.wav
|
| 21 |
+
│ ├── 0002.wav
|
| 22 |
+
│ └── ...
|
| 23 |
+
└── metadata.json
|
| 24 |
+
"""
|
| 25 |
+
output_dir = Path(output_dir)
|
| 26 |
+
audio_output = output_dir / "audio"
|
| 27 |
+
audio_output.mkdir(parents=True, exist_ok=True)
|
| 28 |
+
|
| 29 |
+
# Load metadata (format: {"path": "...", "description": "..."})
|
| 30 |
+
with open(metadata_file) as f:
|
| 31 |
+
metadata = json.load(f)
|
| 32 |
+
|
| 33 |
+
processed = []
|
| 34 |
+
|
| 35 |
+
for idx, item in enumerate(metadata):
|
| 36 |
+
audio_path = Path(audio_dir) / item["path"]
|
| 37 |
+
|
| 38 |
+
# Load and resample to 32kHz
|
| 39 |
+
wav, sr = torchaudio.load(str(audio_path))
|
| 40 |
+
if sr != 32000:
|
| 41 |
+
resampler = torchaudio.transforms.Resample(sr, 32000)
|
| 42 |
+
wav = resampler(wav)
|
| 43 |
+
|
| 44 |
+
# Convert to mono if stereo
|
| 45 |
+
if wav.shape[0] > 1:
|
| 46 |
+
wav = wav.mean(dim=0, keepdim=True)
|
| 47 |
+
|
| 48 |
+
# Save processed audio
|
| 49 |
+
output_path = audio_output / f"{idx:04d}.wav"
|
| 50 |
+
torchaudio.save(str(output_path), wav, sample_rate=32000)
|
| 51 |
+
|
| 52 |
+
processed.append({
|
| 53 |
+
"path": str(output_path.relative_to(output_dir)),
|
| 54 |
+
"description": item["description"],
|
| 55 |
+
"duration": wav.shape[1] / 32000
|
| 56 |
+
})
|
| 57 |
+
|
| 58 |
+
# Save processed metadata
|
| 59 |
+
with open(output_dir / "metadata.json", "w") as f:
|
| 60 |
+
json.dump(processed, f, indent=2)
|
| 61 |
+
|
| 62 |
+
print(f"Processed {len(processed)} samples")
|
| 63 |
+
return processed
|
| 64 |
+
```
|
| 65 |
+
|
| 66 |
+
### Fine-tuning with dora
|
| 67 |
+
|
| 68 |
+
```bash
|
| 69 |
+
# AudioCraft uses dora for experiment management
|
| 70 |
+
# Install dora
|
| 71 |
+
pip install dora-search
|
| 72 |
+
|
| 73 |
+
# Clone AudioCraft
|
| 74 |
+
git clone https://github.com/facebookresearch/audiocraft.git
|
| 75 |
+
cd audiocraft
|
| 76 |
+
|
| 77 |
+
# Create config for fine-tuning
|
| 78 |
+
cat > config/solver/musicgen/finetune.yaml << 'EOF'
|
| 79 |
+
defaults:
|
| 80 |
+
- musicgen/musicgen_base
|
| 81 |
+
- /model: lm/musicgen_lm
|
| 82 |
+
- /conditioner: cond_base
|
| 83 |
+
|
| 84 |
+
solver: musicgen
|
| 85 |
+
autocast: true
|
| 86 |
+
autocast_dtype: float16
|
| 87 |
+
|
| 88 |
+
optim:
|
| 89 |
+
epochs: 100
|
| 90 |
+
batch_size: 4
|
| 91 |
+
lr: 1e-4
|
| 92 |
+
ema: 0.999
|
| 93 |
+
optimizer: adamw
|
| 94 |
+
|
| 95 |
+
dataset:
|
| 96 |
+
batch_size: 4
|
| 97 |
+
num_workers: 4
|
| 98 |
+
train:
|
| 99 |
+
- dset: your_dataset
|
| 100 |
+
root: /path/to/dataset
|
| 101 |
+
valid:
|
| 102 |
+
- dset: your_dataset
|
| 103 |
+
root: /path/to/dataset
|
| 104 |
+
|
| 105 |
+
checkpoint:
|
| 106 |
+
save_every: 10
|
| 107 |
+
keep_every_states: null
|
| 108 |
+
EOF
|
| 109 |
+
|
| 110 |
+
# Run fine-tuning
|
| 111 |
+
dora run solver=musicgen/finetune
|
| 112 |
+
```
|
| 113 |
+
|
| 114 |
+
### LoRA fine-tuning
|
| 115 |
+
|
| 116 |
+
```python
|
| 117 |
+
from peft import LoraConfig, get_peft_model
|
| 118 |
+
from audiocraft.models import MusicGen
|
| 119 |
+
import torch
|
| 120 |
+
|
| 121 |
+
# Load base model
|
| 122 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 123 |
+
|
| 124 |
+
# Get the language model component
|
| 125 |
+
lm = model.lm
|
| 126 |
+
|
| 127 |
+
# Configure LoRA
|
| 128 |
+
lora_config = LoraConfig(
|
| 129 |
+
r=8,
|
| 130 |
+
lora_alpha=16,
|
| 131 |
+
target_modules=["q_proj", "v_proj", "k_proj", "out_proj"],
|
| 132 |
+
lora_dropout=0.05,
|
| 133 |
+
bias="none"
|
| 134 |
+
)
|
| 135 |
+
|
| 136 |
+
# Apply LoRA
|
| 137 |
+
lm = get_peft_model(lm, lora_config)
|
| 138 |
+
lm.print_trainable_parameters()
|
| 139 |
+
```
|
| 140 |
+
|
| 141 |
+
## Multi-GPU Training
|
| 142 |
+
|
| 143 |
+
### DataParallel
|
| 144 |
+
|
| 145 |
+
```python
|
| 146 |
+
import torch
|
| 147 |
+
import torch.nn as nn
|
| 148 |
+
from audiocraft.models import MusicGen
|
| 149 |
+
|
| 150 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 151 |
+
|
| 152 |
+
# Wrap LM with DataParallel
|
| 153 |
+
if torch.cuda.device_count() > 1:
|
| 154 |
+
model.lm = nn.DataParallel(model.lm)
|
| 155 |
+
|
| 156 |
+
model.to("cuda")
|
| 157 |
+
```
|
| 158 |
+
|
| 159 |
+
### DistributedDataParallel
|
| 160 |
+
|
| 161 |
+
```python
|
| 162 |
+
import torch.distributed as dist
|
| 163 |
+
from torch.nn.parallel import DistributedDataParallel as DDP
|
| 164 |
+
|
| 165 |
+
def setup(rank, world_size):
|
| 166 |
+
dist.init_process_group("nccl", rank=rank, world_size=world_size)
|
| 167 |
+
torch.cuda.set_device(rank)
|
| 168 |
+
|
| 169 |
+
def train(rank, world_size):
|
| 170 |
+
setup(rank, world_size)
|
| 171 |
+
|
| 172 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 173 |
+
model.lm = model.lm.to(rank)
|
| 174 |
+
model.lm = DDP(model.lm, device_ids=[rank])
|
| 175 |
+
|
| 176 |
+
# Training loop
|
| 177 |
+
# ...
|
| 178 |
+
|
| 179 |
+
dist.destroy_process_group()
|
| 180 |
+
```
|
| 181 |
+
|
| 182 |
+
## Custom Conditioning
|
| 183 |
+
|
| 184 |
+
### Adding new conditioners
|
| 185 |
+
|
| 186 |
+
```python
|
| 187 |
+
from audiocraft.modules.conditioners import BaseConditioner
|
| 188 |
+
import torch
|
| 189 |
+
|
| 190 |
+
class CustomConditioner(BaseConditioner):
|
| 191 |
+
"""Custom conditioner for additional control signals."""
|
| 192 |
+
|
| 193 |
+
def __init__(self, dim, output_dim):
|
| 194 |
+
super().__init__(dim, output_dim)
|
| 195 |
+
self.embed = torch.nn.Linear(dim, output_dim)
|
| 196 |
+
|
| 197 |
+
def forward(self, x):
|
| 198 |
+
return self.embed(x)
|
| 199 |
+
|
| 200 |
+
def tokenize(self, x):
|
| 201 |
+
# Tokenize input for conditioning
|
| 202 |
+
return x
|
| 203 |
+
|
| 204 |
+
# Use with MusicGen
|
| 205 |
+
from audiocraft.models.builders import get_lm_model
|
| 206 |
+
|
| 207 |
+
# Modify model config to include custom conditioner
|
| 208 |
+
# This requires editing the model configuration
|
| 209 |
+
```
|
| 210 |
+
|
| 211 |
+
### Melody conditioning internals
|
| 212 |
+
|
| 213 |
+
```python
|
| 214 |
+
from audiocraft.models import MusicGen
|
| 215 |
+
from audiocraft.modules.codebooks_patterns import DelayedPatternProvider
|
| 216 |
+
import torch
|
| 217 |
+
|
| 218 |
+
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
| 219 |
+
|
| 220 |
+
# Access chroma extractor
|
| 221 |
+
chroma_extractor = model.lm.condition_provider.conditioners.get('chroma')
|
| 222 |
+
|
| 223 |
+
# Manual chroma extraction
|
| 224 |
+
def extract_chroma(audio, sr):
|
| 225 |
+
"""Extract chroma features from audio."""
|
| 226 |
+
import librosa
|
| 227 |
+
|
| 228 |
+
# Compute chroma
|
| 229 |
+
chroma = librosa.feature.chroma_cqt(y=audio.numpy(), sr=sr)
|
| 230 |
+
|
| 231 |
+
return torch.from_numpy(chroma).float()
|
| 232 |
+
|
| 233 |
+
# Use extracted chroma for conditioning
|
| 234 |
+
chroma = extract_chroma(melody_audio, sample_rate)
|
| 235 |
+
```
|
| 236 |
+
|
| 237 |
+
## EnCodec Deep Dive
|
| 238 |
+
|
| 239 |
+
### Custom compression settings
|
| 240 |
+
|
| 241 |
+
```python
|
| 242 |
+
from audiocraft.models import CompressionModel
|
| 243 |
+
import torch
|
| 244 |
+
|
| 245 |
+
# Load EnCodec
|
| 246 |
+
encodec = CompressionModel.get_pretrained('facebook/encodec_32khz')
|
| 247 |
+
|
| 248 |
+
# Access codec parameters
|
| 249 |
+
print(f"Sample rate: {encodec.sample_rate}")
|
| 250 |
+
print(f"Channels: {encodec.channels}")
|
| 251 |
+
print(f"Cardinality: {encodec.cardinality}") # Codebook size
|
| 252 |
+
print(f"Num codebooks: {encodec.num_codebooks}")
|
| 253 |
+
print(f"Frame rate: {encodec.frame_rate}")
|
| 254 |
+
|
| 255 |
+
# Encode with specific bandwidth
|
| 256 |
+
# Lower bandwidth = more compression, lower quality
|
| 257 |
+
encodec.set_target_bandwidth(6.0) # 6 kbps
|
| 258 |
+
|
| 259 |
+
audio = torch.randn(1, 1, 32000) # 1 second
|
| 260 |
+
encoded = encodec.encode(audio)
|
| 261 |
+
decoded = encodec.decode(encoded[0])
|
| 262 |
+
```
|
| 263 |
+
|
| 264 |
+
### Streaming encoding
|
| 265 |
+
|
| 266 |
+
```python
|
| 267 |
+
import torch
|
| 268 |
+
from audiocraft.models import CompressionModel
|
| 269 |
+
|
| 270 |
+
encodec = CompressionModel.get_pretrained('facebook/encodec_32khz')
|
| 271 |
+
|
| 272 |
+
def encode_streaming(audio_stream, chunk_size=32000):
|
| 273 |
+
"""Encode audio in streaming fashion."""
|
| 274 |
+
all_codes = []
|
| 275 |
+
|
| 276 |
+
for chunk in audio_stream:
|
| 277 |
+
# Ensure chunk is right shape
|
| 278 |
+
if chunk.dim() == 1:
|
| 279 |
+
chunk = chunk.unsqueeze(0).unsqueeze(0)
|
| 280 |
+
|
| 281 |
+
with torch.no_grad():
|
| 282 |
+
codes = encodec.encode(chunk)[0]
|
| 283 |
+
all_codes.append(codes)
|
| 284 |
+
|
| 285 |
+
return torch.cat(all_codes, dim=-1)
|
| 286 |
+
|
| 287 |
+
def decode_streaming(codes_stream, output_stream):
|
| 288 |
+
"""Decode codes in streaming fashion."""
|
| 289 |
+
for codes in codes_stream:
|
| 290 |
+
with torch.no_grad():
|
| 291 |
+
audio = encodec.decode(codes)
|
| 292 |
+
output_stream.write(audio.cpu().numpy())
|
| 293 |
+
```
|
| 294 |
+
|
| 295 |
+
## MultiBand Diffusion
|
| 296 |
+
|
| 297 |
+
### Using MBD for enhanced quality
|
| 298 |
+
|
| 299 |
+
```python
|
| 300 |
+
from audiocraft.models import MusicGen, MultiBandDiffusion
|
| 301 |
+
|
| 302 |
+
# Load MusicGen
|
| 303 |
+
model = MusicGen.get_pretrained('facebook/musicgen-medium')
|
| 304 |
+
|
| 305 |
+
# Load MultiBand Diffusion
|
| 306 |
+
mbd = MultiBandDiffusion.get_mbd_musicgen()
|
| 307 |
+
|
| 308 |
+
model.set_generation_params(duration=10)
|
| 309 |
+
|
| 310 |
+
# Generate with standard decoder
|
| 311 |
+
descriptions = ["epic orchestral music"]
|
| 312 |
+
wav_standard = model.generate(descriptions)
|
| 313 |
+
|
| 314 |
+
# Generate tokens and use MBD decoder
|
| 315 |
+
with torch.no_grad():
|
| 316 |
+
# Get tokens
|
| 317 |
+
gen_tokens = model.generate_tokens(descriptions)
|
| 318 |
+
|
| 319 |
+
# Decode with MBD
|
| 320 |
+
wav_mbd = mbd.tokens_to_wav(gen_tokens)
|
| 321 |
+
|
| 322 |
+
# Compare quality
|
| 323 |
+
print(f"Standard shape: {wav_standard.shape}")
|
| 324 |
+
print(f"MBD shape: {wav_mbd.shape}")
|
| 325 |
+
```
|
| 326 |
+
|
| 327 |
+
## API Server Deployment
|
| 328 |
+
|
| 329 |
+
### FastAPI server
|
| 330 |
+
|
| 331 |
+
```python
|
| 332 |
+
from fastapi import FastAPI, HTTPException
|
| 333 |
+
from pydantic import BaseModel
|
| 334 |
+
import torch
|
| 335 |
+
import torchaudio
|
| 336 |
+
from audiocraft.models import MusicGen
|
| 337 |
+
import io
|
| 338 |
+
import base64
|
| 339 |
+
|
| 340 |
+
app = FastAPI()
|
| 341 |
+
|
| 342 |
+
# Load model at startup
|
| 343 |
+
model = None
|
| 344 |
+
|
| 345 |
+
@app.on_event("startup")
|
| 346 |
+
async def load_model():
|
| 347 |
+
global model
|
| 348 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 349 |
+
model.set_generation_params(duration=10)
|
| 350 |
+
|
| 351 |
+
class GenerateRequest(BaseModel):
|
| 352 |
+
prompt: str
|
| 353 |
+
duration: float = 10.0
|
| 354 |
+
temperature: float = 1.0
|
| 355 |
+
cfg_coef: float = 3.0
|
| 356 |
+
|
| 357 |
+
class GenerateResponse(BaseModel):
|
| 358 |
+
audio_base64: str
|
| 359 |
+
sample_rate: int
|
| 360 |
+
duration: float
|
| 361 |
+
|
| 362 |
+
@app.post("/generate", response_model=GenerateResponse)
|
| 363 |
+
async def generate(request: GenerateRequest):
|
| 364 |
+
if model is None:
|
| 365 |
+
raise HTTPException(status_code=500, detail="Model not loaded")
|
| 366 |
+
|
| 367 |
+
try:
|
| 368 |
+
model.set_generation_params(
|
| 369 |
+
duration=min(request.duration, 30),
|
| 370 |
+
temperature=request.temperature,
|
| 371 |
+
cfg_coef=request.cfg_coef
|
| 372 |
+
)
|
| 373 |
+
|
| 374 |
+
with torch.no_grad():
|
| 375 |
+
wav = model.generate([request.prompt])
|
| 376 |
+
|
| 377 |
+
# Convert to bytes
|
| 378 |
+
buffer = io.BytesIO()
|
| 379 |
+
torchaudio.save(buffer, wav[0].cpu(), sample_rate=32000, format="wav")
|
| 380 |
+
buffer.seek(0)
|
| 381 |
+
|
| 382 |
+
audio_base64 = base64.b64encode(buffer.read()).decode()
|
| 383 |
+
|
| 384 |
+
return GenerateResponse(
|
| 385 |
+
audio_base64=audio_base64,
|
| 386 |
+
sample_rate=32000,
|
| 387 |
+
duration=wav.shape[-1] / 32000
|
| 388 |
+
)
|
| 389 |
+
|
| 390 |
+
except Exception as e:
|
| 391 |
+
raise HTTPException(status_code=500, detail=str(e))
|
| 392 |
+
|
| 393 |
+
@app.get("/health")
|
| 394 |
+
async def health():
|
| 395 |
+
return {"status": "ok", "model_loaded": model is not None}
|
| 396 |
+
|
| 397 |
+
# Run: uvicorn server:app --host 0.0.0.0 --port 8000
|
| 398 |
+
```
|
| 399 |
+
|
| 400 |
+
### Batch processing service
|
| 401 |
+
|
| 402 |
+
```python
|
| 403 |
+
import asyncio
|
| 404 |
+
from concurrent.futures import ThreadPoolExecutor
|
| 405 |
+
import torch
|
| 406 |
+
from audiocraft.models import MusicGen
|
| 407 |
+
|
| 408 |
+
class MusicGenService:
|
| 409 |
+
def __init__(self, model_name='facebook/musicgen-small', max_workers=2):
|
| 410 |
+
self.model = MusicGen.get_pretrained(model_name)
|
| 411 |
+
self.executor = ThreadPoolExecutor(max_workers=max_workers)
|
| 412 |
+
self.lock = asyncio.Lock()
|
| 413 |
+
|
| 414 |
+
async def generate_async(self, prompt, duration=10):
|
| 415 |
+
"""Async generation with thread pool."""
|
| 416 |
+
loop = asyncio.get_event_loop()
|
| 417 |
+
|
| 418 |
+
def _generate():
|
| 419 |
+
with torch.no_grad():
|
| 420 |
+
self.model.set_generation_params(duration=duration)
|
| 421 |
+
return self.model.generate([prompt])
|
| 422 |
+
|
| 423 |
+
# Run in thread pool
|
| 424 |
+
wav = await loop.run_in_executor(self.executor, _generate)
|
| 425 |
+
return wav[0].cpu()
|
| 426 |
+
|
| 427 |
+
async def generate_batch_async(self, prompts, duration=10):
|
| 428 |
+
"""Process multiple prompts concurrently."""
|
| 429 |
+
tasks = [self.generate_async(p, duration) for p in prompts]
|
| 430 |
+
return await asyncio.gather(*tasks)
|
| 431 |
+
|
| 432 |
+
# Usage
|
| 433 |
+
service = MusicGenService()
|
| 434 |
+
|
| 435 |
+
async def main():
|
| 436 |
+
prompts = ["jazz piano", "rock guitar", "electronic beats"]
|
| 437 |
+
results = await service.generate_batch_async(prompts)
|
| 438 |
+
return results
|
| 439 |
+
```
|
| 440 |
+
|
| 441 |
+
## Integration Patterns
|
| 442 |
+
|
| 443 |
+
### LangChain tool
|
| 444 |
+
|
| 445 |
+
```python
|
| 446 |
+
from langchain.tools import BaseTool
|
| 447 |
+
import torch
|
| 448 |
+
import torchaudio
|
| 449 |
+
from audiocraft.models import MusicGen
|
| 450 |
+
import tempfile
|
| 451 |
+
|
| 452 |
+
class MusicGeneratorTool(BaseTool):
|
| 453 |
+
name = "music_generator"
|
| 454 |
+
description = "Generate music from a text description. Input should be a detailed description of the music style, mood, and instruments."
|
| 455 |
+
|
| 456 |
+
def __init__(self):
|
| 457 |
+
super().__init__()
|
| 458 |
+
self.model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 459 |
+
self.model.set_generation_params(duration=15)
|
| 460 |
+
|
| 461 |
+
def _run(self, description: str) -> str:
|
| 462 |
+
with torch.no_grad():
|
| 463 |
+
wav = self.model.generate([description])
|
| 464 |
+
|
| 465 |
+
# Save to temp file
|
| 466 |
+
with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
|
| 467 |
+
torchaudio.save(f.name, wav[0].cpu(), sample_rate=32000)
|
| 468 |
+
return f"Generated music saved to: {f.name}"
|
| 469 |
+
|
| 470 |
+
async def _arun(self, description: str) -> str:
|
| 471 |
+
return self._run(description)
|
| 472 |
+
```
|
| 473 |
+
|
| 474 |
+
### Gradio with advanced controls
|
| 475 |
+
|
| 476 |
+
```python
|
| 477 |
+
import gradio as gr
|
| 478 |
+
import torch
|
| 479 |
+
import torchaudio
|
| 480 |
+
from audiocraft.models import MusicGen
|
| 481 |
+
|
| 482 |
+
models = {}
|
| 483 |
+
|
| 484 |
+
def load_model(model_size):
|
| 485 |
+
if model_size not in models:
|
| 486 |
+
model_name = f"facebook/musicgen-{model_size}"
|
| 487 |
+
models[model_size] = MusicGen.get_pretrained(model_name)
|
| 488 |
+
return models[model_size]
|
| 489 |
+
|
| 490 |
+
def generate(prompt, duration, temperature, cfg_coef, top_k, model_size):
|
| 491 |
+
model = load_model(model_size)
|
| 492 |
+
|
| 493 |
+
model.set_generation_params(
|
| 494 |
+
duration=duration,
|
| 495 |
+
temperature=temperature,
|
| 496 |
+
cfg_coef=cfg_coef,
|
| 497 |
+
top_k=top_k
|
| 498 |
+
)
|
| 499 |
+
|
| 500 |
+
with torch.no_grad():
|
| 501 |
+
wav = model.generate([prompt])
|
| 502 |
+
|
| 503 |
+
# Save
|
| 504 |
+
path = "output.wav"
|
| 505 |
+
torchaudio.save(path, wav[0].cpu(), sample_rate=32000)
|
| 506 |
+
return path
|
| 507 |
+
|
| 508 |
+
demo = gr.Interface(
|
| 509 |
+
fn=generate,
|
| 510 |
+
inputs=[
|
| 511 |
+
gr.Textbox(label="Prompt", lines=3),
|
| 512 |
+
gr.Slider(1, 30, value=10, label="Duration (s)"),
|
| 513 |
+
gr.Slider(0.1, 2.0, value=1.0, label="Temperature"),
|
| 514 |
+
gr.Slider(0.5, 10.0, value=3.0, label="CFG Coefficient"),
|
| 515 |
+
gr.Slider(50, 500, value=250, step=50, label="Top-K"),
|
| 516 |
+
gr.Dropdown(["small", "medium", "large"], value="small", label="Model Size")
|
| 517 |
+
],
|
| 518 |
+
outputs=gr.Audio(label="Generated Music"),
|
| 519 |
+
title="MusicGen Advanced",
|
| 520 |
+
allow_flagging="never"
|
| 521 |
+
)
|
| 522 |
+
|
| 523 |
+
demo.launch(share=True)
|
| 524 |
+
```
|
| 525 |
+
|
| 526 |
+
## Audio Processing Pipeline
|
| 527 |
+
|
| 528 |
+
### Post-processing chain
|
| 529 |
+
|
| 530 |
+
```python
|
| 531 |
+
import torch
|
| 532 |
+
import torchaudio
|
| 533 |
+
import torchaudio.transforms as T
|
| 534 |
+
import numpy as np
|
| 535 |
+
|
| 536 |
+
class AudioPostProcessor:
|
| 537 |
+
def __init__(self, sample_rate=32000):
|
| 538 |
+
self.sample_rate = sample_rate
|
| 539 |
+
|
| 540 |
+
def normalize(self, audio, target_db=-14.0):
|
| 541 |
+
"""Normalize audio to target loudness."""
|
| 542 |
+
rms = torch.sqrt(torch.mean(audio ** 2))
|
| 543 |
+
target_rms = 10 ** (target_db / 20)
|
| 544 |
+
gain = target_rms / (rms + 1e-8)
|
| 545 |
+
return audio * gain
|
| 546 |
+
|
| 547 |
+
def fade_in_out(self, audio, fade_duration=0.1):
|
| 548 |
+
"""Apply fade in/out."""
|
| 549 |
+
fade_samples = int(fade_duration * self.sample_rate)
|
| 550 |
+
|
| 551 |
+
# Create fade curves
|
| 552 |
+
fade_in = torch.linspace(0, 1, fade_samples)
|
| 553 |
+
fade_out = torch.linspace(1, 0, fade_samples)
|
| 554 |
+
|
| 555 |
+
# Apply fades
|
| 556 |
+
audio[..., :fade_samples] *= fade_in
|
| 557 |
+
audio[..., -fade_samples:] *= fade_out
|
| 558 |
+
|
| 559 |
+
return audio
|
| 560 |
+
|
| 561 |
+
def apply_reverb(self, audio, decay=0.5):
|
| 562 |
+
"""Apply simple reverb effect."""
|
| 563 |
+
impulse = torch.zeros(int(self.sample_rate * 0.5))
|
| 564 |
+
impulse[0] = 1.0
|
| 565 |
+
impulse[int(self.sample_rate * 0.1)] = decay * 0.5
|
| 566 |
+
impulse[int(self.sample_rate * 0.2)] = decay * 0.25
|
| 567 |
+
|
| 568 |
+
# Convolve
|
| 569 |
+
audio = torch.nn.functional.conv1d(
|
| 570 |
+
audio.unsqueeze(0),
|
| 571 |
+
impulse.unsqueeze(0).unsqueeze(0),
|
| 572 |
+
padding=len(impulse) // 2
|
| 573 |
+
).squeeze(0)
|
| 574 |
+
|
| 575 |
+
return audio
|
| 576 |
+
|
| 577 |
+
def process(self, audio):
|
| 578 |
+
"""Full processing pipeline."""
|
| 579 |
+
audio = self.normalize(audio)
|
| 580 |
+
audio = self.fade_in_out(audio)
|
| 581 |
+
return audio
|
| 582 |
+
|
| 583 |
+
# Usage with MusicGen
|
| 584 |
+
from audiocraft.models import MusicGen
|
| 585 |
+
|
| 586 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 587 |
+
model.set_generation_params(duration=10)
|
| 588 |
+
|
| 589 |
+
wav = model.generate(["chill ambient music"])
|
| 590 |
+
processor = AudioPostProcessor()
|
| 591 |
+
wav_processed = processor.process(wav[0].cpu())
|
| 592 |
+
|
| 593 |
+
torchaudio.save("processed.wav", wav_processed, sample_rate=32000)
|
| 594 |
+
```
|
| 595 |
+
|
| 596 |
+
## Evaluation
|
| 597 |
+
|
| 598 |
+
### Audio quality metrics
|
| 599 |
+
|
| 600 |
+
```python
|
| 601 |
+
import torch
|
| 602 |
+
from audiocraft.metrics import CLAPTextConsistencyMetric
|
| 603 |
+
from audiocraft.data.audio import audio_read
|
| 604 |
+
|
| 605 |
+
def evaluate_generation(audio_path, text_prompt):
|
| 606 |
+
"""Evaluate generated audio quality."""
|
| 607 |
+
# Load audio
|
| 608 |
+
wav, sr = audio_read(audio_path)
|
| 609 |
+
|
| 610 |
+
# CLAP consistency (text-audio alignment)
|
| 611 |
+
clap_metric = CLAPTextConsistencyMetric()
|
| 612 |
+
clap_score = clap_metric.compute(wav, [text_prompt])
|
| 613 |
+
|
| 614 |
+
return {
|
| 615 |
+
"clap_score": clap_score,
|
| 616 |
+
"duration": wav.shape[-1] / sr
|
| 617 |
+
}
|
| 618 |
+
|
| 619 |
+
# Batch evaluation
|
| 620 |
+
def evaluate_batch(generations):
|
| 621 |
+
"""Evaluate multiple generations."""
|
| 622 |
+
results = []
|
| 623 |
+
for gen in generations:
|
| 624 |
+
result = evaluate_generation(gen["path"], gen["prompt"])
|
| 625 |
+
result["prompt"] = gen["prompt"]
|
| 626 |
+
results.append(result)
|
| 627 |
+
|
| 628 |
+
# Aggregate
|
| 629 |
+
avg_clap = sum(r["clap_score"] for r in results) / len(results)
|
| 630 |
+
return {
|
| 631 |
+
"individual": results,
|
| 632 |
+
"average_clap": avg_clap
|
| 633 |
+
}
|
| 634 |
+
```
|
| 635 |
+
|
| 636 |
+
## Model Comparison
|
| 637 |
+
|
| 638 |
+
### MusicGen variants benchmark
|
| 639 |
+
|
| 640 |
+
| Model | CLAP Score | Generation Time (10s) | VRAM |
|
| 641 |
+
|-------|------------|----------------------|------|
|
| 642 |
+
| musicgen-small | 0.35 | ~5s | 2GB |
|
| 643 |
+
| musicgen-medium | 0.42 | ~15s | 4GB |
|
| 644 |
+
| musicgen-large | 0.48 | ~30s | 8GB |
|
| 645 |
+
| musicgen-melody | 0.45 | ~15s | 4GB |
|
| 646 |
+
| musicgen-stereo-medium | 0.41 | ~18s | 5GB |
|
| 647 |
+
|
| 648 |
+
### Prompt engineering tips
|
| 649 |
+
|
| 650 |
+
```python
|
| 651 |
+
# Good prompts - specific and descriptive
|
| 652 |
+
good_prompts = [
|
| 653 |
+
"upbeat electronic dance music with synthesizer leads and punchy drums at 128 bpm",
|
| 654 |
+
"melancholic piano ballad with strings, slow tempo, emotional and cinematic",
|
| 655 |
+
"funky disco groove with slap bass, brass section, and rhythmic guitar"
|
| 656 |
+
]
|
| 657 |
+
|
| 658 |
+
# Bad prompts - too vague
|
| 659 |
+
bad_prompts = [
|
| 660 |
+
"nice music",
|
| 661 |
+
"song",
|
| 662 |
+
"good beat"
|
| 663 |
+
]
|
| 664 |
+
|
| 665 |
+
# Structure: [mood] [genre] with [instruments] at [tempo/style]
|
| 666 |
+
```
|
optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md
ADDED
|
@@ -0,0 +1,504 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# AudioCraft Troubleshooting Guide
|
| 2 |
+
|
| 3 |
+
## Installation Issues
|
| 4 |
+
|
| 5 |
+
### Import errors
|
| 6 |
+
|
| 7 |
+
**Error**: `ModuleNotFoundError: No module named 'audiocraft'`
|
| 8 |
+
|
| 9 |
+
**Solutions**:
|
| 10 |
+
```bash
|
| 11 |
+
# Install from PyPI
|
| 12 |
+
pip install audiocraft
|
| 13 |
+
|
| 14 |
+
# Or from GitHub
|
| 15 |
+
pip install git+https://github.com/facebookresearch/audiocraft.git
|
| 16 |
+
|
| 17 |
+
# Verify installation
|
| 18 |
+
python -c "from audiocraft.models import MusicGen; print('OK')"
|
| 19 |
+
```
|
| 20 |
+
|
| 21 |
+
### FFmpeg not found
|
| 22 |
+
|
| 23 |
+
**Error**: `RuntimeError: ffmpeg not found`
|
| 24 |
+
|
| 25 |
+
**Solutions**:
|
| 26 |
+
```bash
|
| 27 |
+
# Ubuntu/Debian
|
| 28 |
+
sudo apt-get install ffmpeg
|
| 29 |
+
|
| 30 |
+
# macOS
|
| 31 |
+
brew install ffmpeg
|
| 32 |
+
|
| 33 |
+
# Windows (using conda)
|
| 34 |
+
conda install -c conda-forge ffmpeg
|
| 35 |
+
|
| 36 |
+
# Verify
|
| 37 |
+
ffmpeg -version
|
| 38 |
+
```
|
| 39 |
+
|
| 40 |
+
### PyTorch CUDA mismatch
|
| 41 |
+
|
| 42 |
+
**Error**: `RuntimeError: CUDA error: no kernel image is available`
|
| 43 |
+
|
| 44 |
+
**Solutions**:
|
| 45 |
+
```bash
|
| 46 |
+
# Check CUDA version
|
| 47 |
+
nvcc --version
|
| 48 |
+
python -c "import torch; print(torch.version.cuda)"
|
| 49 |
+
|
| 50 |
+
# Install matching PyTorch
|
| 51 |
+
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
|
| 52 |
+
|
| 53 |
+
# For CUDA 11.8
|
| 54 |
+
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118
|
| 55 |
+
```
|
| 56 |
+
|
| 57 |
+
### xformers issues
|
| 58 |
+
|
| 59 |
+
**Error**: `ImportError: xformers` related errors
|
| 60 |
+
|
| 61 |
+
**Solutions**:
|
| 62 |
+
```bash
|
| 63 |
+
# Install xformers for memory efficiency
|
| 64 |
+
pip install xformers
|
| 65 |
+
|
| 66 |
+
# Or disable xformers
|
| 67 |
+
export AUDIOCRAFT_USE_XFORMERS=0
|
| 68 |
+
|
| 69 |
+
# In Python
|
| 70 |
+
import os
|
| 71 |
+
os.environ["AUDIOCRAFT_USE_XFORMERS"] = "0"
|
| 72 |
+
from audiocraft.models import MusicGen
|
| 73 |
+
```
|
| 74 |
+
|
| 75 |
+
## Model Loading Issues
|
| 76 |
+
|
| 77 |
+
### Out of memory during load
|
| 78 |
+
|
| 79 |
+
**Error**: `torch.cuda.OutOfMemoryError` during model loading
|
| 80 |
+
|
| 81 |
+
**Solutions**:
|
| 82 |
+
```python
|
| 83 |
+
# Use smaller model
|
| 84 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 85 |
+
|
| 86 |
+
# Force CPU loading first
|
| 87 |
+
import torch
|
| 88 |
+
device = "cpu"
|
| 89 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small', device=device)
|
| 90 |
+
model = model.to("cuda")
|
| 91 |
+
|
| 92 |
+
# Use HuggingFace with device_map
|
| 93 |
+
from transformers import MusicgenForConditionalGeneration
|
| 94 |
+
model = MusicgenForConditionalGeneration.from_pretrained(
|
| 95 |
+
"facebook/musicgen-small",
|
| 96 |
+
device_map="auto"
|
| 97 |
+
)
|
| 98 |
+
```
|
| 99 |
+
|
| 100 |
+
### Download failures
|
| 101 |
+
|
| 102 |
+
**Error**: Connection errors or incomplete downloads
|
| 103 |
+
|
| 104 |
+
**Solutions**:
|
| 105 |
+
```python
|
| 106 |
+
# Set cache directory
|
| 107 |
+
import os
|
| 108 |
+
os.environ["AUDIOCRAFT_CACHE_DIR"] = "/path/to/cache"
|
| 109 |
+
|
| 110 |
+
# Or for HuggingFace
|
| 111 |
+
os.environ["HF_HOME"] = "/path/to/hf_cache"
|
| 112 |
+
|
| 113 |
+
# Resume download
|
| 114 |
+
from huggingface_hub import snapshot_download
|
| 115 |
+
snapshot_download("facebook/musicgen-small", resume_download=True)
|
| 116 |
+
|
| 117 |
+
# Use local files
|
| 118 |
+
model = MusicGen.get_pretrained('/local/path/to/model')
|
| 119 |
+
```
|
| 120 |
+
|
| 121 |
+
### Wrong model type
|
| 122 |
+
|
| 123 |
+
**Error**: Loading wrong model for task
|
| 124 |
+
|
| 125 |
+
**Solutions**:
|
| 126 |
+
```python
|
| 127 |
+
# For text-to-music: use MusicGen
|
| 128 |
+
from audiocraft.models import MusicGen
|
| 129 |
+
model = MusicGen.get_pretrained('facebook/musicgen-medium')
|
| 130 |
+
|
| 131 |
+
# For text-to-sound: use AudioGen
|
| 132 |
+
from audiocraft.models import AudioGen
|
| 133 |
+
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
| 134 |
+
|
| 135 |
+
# For melody conditioning: use melody variant
|
| 136 |
+
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
| 137 |
+
|
| 138 |
+
# For stereo: use stereo variant
|
| 139 |
+
model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
|
| 140 |
+
```
|
| 141 |
+
|
| 142 |
+
## Generation Issues
|
| 143 |
+
|
| 144 |
+
### Empty or silent output
|
| 145 |
+
|
| 146 |
+
**Problem**: Generated audio is silent or very quiet
|
| 147 |
+
|
| 148 |
+
**Solutions**:
|
| 149 |
+
```python
|
| 150 |
+
import torch
|
| 151 |
+
|
| 152 |
+
# Check output
|
| 153 |
+
wav = model.generate(["upbeat music"])
|
| 154 |
+
print(f"Shape: {wav.shape}")
|
| 155 |
+
print(f"Max amplitude: {wav.abs().max().item()}")
|
| 156 |
+
print(f"Mean amplitude: {wav.abs().mean().item()}")
|
| 157 |
+
|
| 158 |
+
# If too quiet, normalize
|
| 159 |
+
def normalize_audio(audio, target_db=-14.0):
|
| 160 |
+
rms = torch.sqrt(torch.mean(audio ** 2))
|
| 161 |
+
target_rms = 10 ** (target_db / 20)
|
| 162 |
+
gain = target_rms / (rms + 1e-8)
|
| 163 |
+
return audio * gain
|
| 164 |
+
|
| 165 |
+
wav_normalized = normalize_audio(wav)
|
| 166 |
+
```
|
| 167 |
+
|
| 168 |
+
### Poor quality output
|
| 169 |
+
|
| 170 |
+
**Problem**: Generated music sounds bad or noisy
|
| 171 |
+
|
| 172 |
+
**Solutions**:
|
| 173 |
+
```python
|
| 174 |
+
# Use larger model
|
| 175 |
+
model = MusicGen.get_pretrained('facebook/musicgen-large')
|
| 176 |
+
|
| 177 |
+
# Adjust generation parameters
|
| 178 |
+
model.set_generation_params(
|
| 179 |
+
duration=15,
|
| 180 |
+
top_k=250, # Increase for more diversity
|
| 181 |
+
temperature=0.8, # Lower for more focused output
|
| 182 |
+
cfg_coef=4.0 # Increase for better text adherence
|
| 183 |
+
)
|
| 184 |
+
|
| 185 |
+
# Use better prompts
|
| 186 |
+
# Bad: "music"
|
| 187 |
+
# Good: "upbeat electronic dance music with synthesizers and punchy drums"
|
| 188 |
+
|
| 189 |
+
# Try MultiBand Diffusion
|
| 190 |
+
from audiocraft.models import MultiBandDiffusion
|
| 191 |
+
mbd = MultiBandDiffusion.get_mbd_musicgen()
|
| 192 |
+
tokens = model.generate_tokens(["prompt"])
|
| 193 |
+
wav = mbd.tokens_to_wav(tokens)
|
| 194 |
+
```
|
| 195 |
+
|
| 196 |
+
### Generation too short
|
| 197 |
+
|
| 198 |
+
**Problem**: Audio shorter than expected
|
| 199 |
+
|
| 200 |
+
**Solutions**:
|
| 201 |
+
```python
|
| 202 |
+
# Check duration setting
|
| 203 |
+
model.set_generation_params(duration=30) # Set before generate
|
| 204 |
+
|
| 205 |
+
# Verify in generation
|
| 206 |
+
print(f"Duration setting: {model.generation_params}")
|
| 207 |
+
|
| 208 |
+
# Check output shape
|
| 209 |
+
wav = model.generate(["prompt"])
|
| 210 |
+
actual_duration = wav.shape[-1] / 32000
|
| 211 |
+
print(f"Actual duration: {actual_duration}s")
|
| 212 |
+
|
| 213 |
+
# Note: max duration is typically 30s
|
| 214 |
+
```
|
| 215 |
+
|
| 216 |
+
### Melody conditioning fails
|
| 217 |
+
|
| 218 |
+
**Error**: Issues with melody-conditioned generation
|
| 219 |
+
|
| 220 |
+
**Solutions**:
|
| 221 |
+
```python
|
| 222 |
+
import torchaudio
|
| 223 |
+
from audiocraft.models import MusicGen
|
| 224 |
+
|
| 225 |
+
# Load melody model (not base model)
|
| 226 |
+
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
| 227 |
+
|
| 228 |
+
# Load and prepare melody
|
| 229 |
+
melody, sr = torchaudio.load("melody.wav")
|
| 230 |
+
|
| 231 |
+
# Resample to model sample rate if needed
|
| 232 |
+
if sr != 32000:
|
| 233 |
+
resampler = torchaudio.transforms.Resample(sr, 32000)
|
| 234 |
+
melody = resampler(melody)
|
| 235 |
+
|
| 236 |
+
# Ensure correct shape [batch, channels, samples]
|
| 237 |
+
if melody.dim() == 1:
|
| 238 |
+
melody = melody.unsqueeze(0).unsqueeze(0)
|
| 239 |
+
elif melody.dim() == 2:
|
| 240 |
+
melody = melody.unsqueeze(0)
|
| 241 |
+
|
| 242 |
+
# Convert stereo to mono
|
| 243 |
+
if melody.shape[1] > 1:
|
| 244 |
+
melody = melody.mean(dim=1, keepdim=True)
|
| 245 |
+
|
| 246 |
+
# Generate with melody
|
| 247 |
+
model.set_generation_params(duration=min(melody.shape[-1] / 32000, 30))
|
| 248 |
+
wav = model.generate_with_chroma(["piano cover"], melody, 32000)
|
| 249 |
+
```
|
| 250 |
+
|
| 251 |
+
## Memory Issues
|
| 252 |
+
|
| 253 |
+
### CUDA out of memory
|
| 254 |
+
|
| 255 |
+
**Error**: `torch.cuda.OutOfMemoryError: CUDA out of memory`
|
| 256 |
+
|
| 257 |
+
**Solutions**:
|
| 258 |
+
```python
|
| 259 |
+
import torch
|
| 260 |
+
|
| 261 |
+
# Clear cache before generation
|
| 262 |
+
torch.cuda.empty_cache()
|
| 263 |
+
|
| 264 |
+
# Use smaller model
|
| 265 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 266 |
+
|
| 267 |
+
# Reduce duration
|
| 268 |
+
model.set_generation_params(duration=10) # Instead of 30
|
| 269 |
+
|
| 270 |
+
# Generate one at a time
|
| 271 |
+
for prompt in prompts:
|
| 272 |
+
wav = model.generate([prompt])
|
| 273 |
+
save_audio(wav)
|
| 274 |
+
torch.cuda.empty_cache()
|
| 275 |
+
|
| 276 |
+
# Use CPU for very large generations
|
| 277 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small', device="cpu")
|
| 278 |
+
```
|
| 279 |
+
|
| 280 |
+
### Memory leak during batch processing
|
| 281 |
+
|
| 282 |
+
**Problem**: Memory grows over time
|
| 283 |
+
|
| 284 |
+
**Solutions**:
|
| 285 |
+
```python
|
| 286 |
+
import gc
|
| 287 |
+
import torch
|
| 288 |
+
|
| 289 |
+
def generate_with_cleanup(model, prompts):
|
| 290 |
+
results = []
|
| 291 |
+
|
| 292 |
+
for prompt in prompts:
|
| 293 |
+
with torch.no_grad():
|
| 294 |
+
wav = model.generate([prompt])
|
| 295 |
+
results.append(wav.cpu())
|
| 296 |
+
|
| 297 |
+
# Cleanup
|
| 298 |
+
del wav
|
| 299 |
+
gc.collect()
|
| 300 |
+
torch.cuda.empty_cache()
|
| 301 |
+
|
| 302 |
+
return results
|
| 303 |
+
|
| 304 |
+
# Use context manager
|
| 305 |
+
with torch.inference_mode():
|
| 306 |
+
wav = model.generate(["prompt"])
|
| 307 |
+
```
|
| 308 |
+
|
| 309 |
+
## Audio Format Issues
|
| 310 |
+
|
| 311 |
+
### Wrong sample rate
|
| 312 |
+
|
| 313 |
+
**Problem**: Audio plays at wrong speed
|
| 314 |
+
|
| 315 |
+
**Solutions**:
|
| 316 |
+
```python
|
| 317 |
+
import torchaudio
|
| 318 |
+
|
| 319 |
+
# MusicGen outputs at 32kHz
|
| 320 |
+
sample_rate = 32000
|
| 321 |
+
|
| 322 |
+
# AudioGen outputs at 16kHz
|
| 323 |
+
sample_rate = 16000
|
| 324 |
+
|
| 325 |
+
# Always use correct rate when saving
|
| 326 |
+
torchaudio.save("output.wav", wav[0].cpu(), sample_rate=sample_rate)
|
| 327 |
+
|
| 328 |
+
# Resample if needed
|
| 329 |
+
resampler = torchaudio.transforms.Resample(32000, 44100)
|
| 330 |
+
wav_resampled = resampler(wav)
|
| 331 |
+
```
|
| 332 |
+
|
| 333 |
+
### Stereo/mono mismatch
|
| 334 |
+
|
| 335 |
+
**Problem**: Wrong number of channels
|
| 336 |
+
|
| 337 |
+
**Solutions**:
|
| 338 |
+
```python
|
| 339 |
+
# Check model type
|
| 340 |
+
print(f"Audio channels: {wav.shape}")
|
| 341 |
+
# Mono: [batch, 1, samples]
|
| 342 |
+
# Stereo: [batch, 2, samples]
|
| 343 |
+
|
| 344 |
+
# Convert mono to stereo
|
| 345 |
+
if wav.shape[1] == 1:
|
| 346 |
+
wav_stereo = wav.repeat(1, 2, 1)
|
| 347 |
+
|
| 348 |
+
# Convert stereo to mono
|
| 349 |
+
if wav.shape[1] == 2:
|
| 350 |
+
wav_mono = wav.mean(dim=1, keepdim=True)
|
| 351 |
+
|
| 352 |
+
# Use stereo model for stereo output
|
| 353 |
+
model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
|
| 354 |
+
```
|
| 355 |
+
|
| 356 |
+
### Clipping and distortion
|
| 357 |
+
|
| 358 |
+
**Problem**: Audio has clipping or distortion
|
| 359 |
+
|
| 360 |
+
**Solutions**:
|
| 361 |
+
```python
|
| 362 |
+
import torch
|
| 363 |
+
|
| 364 |
+
# Check for clipping
|
| 365 |
+
max_val = wav.abs().max().item()
|
| 366 |
+
print(f"Max amplitude: {max_val}")
|
| 367 |
+
|
| 368 |
+
# Normalize to prevent clipping
|
| 369 |
+
if max_val > 1.0:
|
| 370 |
+
wav = wav / max_val
|
| 371 |
+
|
| 372 |
+
# Apply soft clipping
|
| 373 |
+
def soft_clip(x, threshold=0.9):
|
| 374 |
+
return torch.tanh(x / threshold) * threshold
|
| 375 |
+
|
| 376 |
+
wav_clipped = soft_clip(wav)
|
| 377 |
+
|
| 378 |
+
# Lower temperature during generation
|
| 379 |
+
model.set_generation_params(temperature=0.7) # More controlled
|
| 380 |
+
```
|
| 381 |
+
|
| 382 |
+
## HuggingFace Transformers Issues
|
| 383 |
+
|
| 384 |
+
### Processor errors
|
| 385 |
+
|
| 386 |
+
**Error**: Issues with MusicgenProcessor
|
| 387 |
+
|
| 388 |
+
**Solutions**:
|
| 389 |
+
```python
|
| 390 |
+
from transformers import AutoProcessor, MusicgenForConditionalGeneration
|
| 391 |
+
|
| 392 |
+
# Load matching processor and model
|
| 393 |
+
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
|
| 394 |
+
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
|
| 395 |
+
|
| 396 |
+
# Ensure inputs are on same device
|
| 397 |
+
inputs = processor(
|
| 398 |
+
text=["prompt"],
|
| 399 |
+
padding=True,
|
| 400 |
+
return_tensors="pt"
|
| 401 |
+
).to("cuda")
|
| 402 |
+
|
| 403 |
+
# Check processor configuration
|
| 404 |
+
print(processor.tokenizer)
|
| 405 |
+
print(processor.feature_extractor)
|
| 406 |
+
```
|
| 407 |
+
|
| 408 |
+
### Generation parameter errors
|
| 409 |
+
|
| 410 |
+
**Error**: Invalid generation parameters
|
| 411 |
+
|
| 412 |
+
**Solutions**:
|
| 413 |
+
```python
|
| 414 |
+
# HuggingFace uses different parameter names
|
| 415 |
+
audio_values = model.generate(
|
| 416 |
+
**inputs,
|
| 417 |
+
do_sample=True, # Enable sampling
|
| 418 |
+
guidance_scale=3.0, # CFG (not cfg_coef)
|
| 419 |
+
max_new_tokens=256, # Token limit (not duration)
|
| 420 |
+
temperature=1.0
|
| 421 |
+
)
|
| 422 |
+
|
| 423 |
+
# Calculate tokens from duration
|
| 424 |
+
# ~50 tokens per second
|
| 425 |
+
duration_seconds = 10
|
| 426 |
+
max_tokens = duration_seconds * 50
|
| 427 |
+
audio_values = model.generate(**inputs, max_new_tokens=max_tokens)
|
| 428 |
+
```
|
| 429 |
+
|
| 430 |
+
## Performance Issues
|
| 431 |
+
|
| 432 |
+
### Slow generation
|
| 433 |
+
|
| 434 |
+
**Problem**: Generation takes too long
|
| 435 |
+
|
| 436 |
+
**Solutions**:
|
| 437 |
+
```python
|
| 438 |
+
# Use smaller model
|
| 439 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 440 |
+
|
| 441 |
+
# Reduce duration
|
| 442 |
+
model.set_generation_params(duration=10)
|
| 443 |
+
|
| 444 |
+
# Use GPU
|
| 445 |
+
model.to("cuda")
|
| 446 |
+
|
| 447 |
+
# Enable flash attention if available
|
| 448 |
+
# (requires compatible hardware)
|
| 449 |
+
|
| 450 |
+
# Batch multiple prompts
|
| 451 |
+
prompts = ["prompt1", "prompt2", "prompt3"]
|
| 452 |
+
wav = model.generate(prompts) # Single batch is faster than loop
|
| 453 |
+
|
| 454 |
+
# Use compile (PyTorch 2.0+)
|
| 455 |
+
model.lm = torch.compile(model.lm)
|
| 456 |
+
```
|
| 457 |
+
|
| 458 |
+
### CPU fallback
|
| 459 |
+
|
| 460 |
+
**Problem**: Generation running on CPU instead of GPU
|
| 461 |
+
|
| 462 |
+
**Solutions**:
|
| 463 |
+
```python
|
| 464 |
+
import torch
|
| 465 |
+
|
| 466 |
+
# Check CUDA availability
|
| 467 |
+
print(f"CUDA available: {torch.cuda.is_available()}")
|
| 468 |
+
print(f"CUDA device: {torch.cuda.get_device_name(0)}")
|
| 469 |
+
|
| 470 |
+
# Explicitly move to GPU
|
| 471 |
+
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
| 472 |
+
model.to("cuda")
|
| 473 |
+
|
| 474 |
+
# Verify model device
|
| 475 |
+
print(f"Model device: {next(model.lm.parameters()).device}")
|
| 476 |
+
```
|
| 477 |
+
|
| 478 |
+
## Common Error Messages
|
| 479 |
+
|
| 480 |
+
| Error | Cause | Solution |
|
| 481 |
+
|-------|-------|----------|
|
| 482 |
+
| `CUDA out of memory` | Model too large | Use smaller model, reduce duration |
|
| 483 |
+
| `ffmpeg not found` | FFmpeg not installed | Install FFmpeg |
|
| 484 |
+
| `No module named 'audiocraft'` | Not installed | `pip install audiocraft` |
|
| 485 |
+
| `RuntimeError: Expected 3D tensor` | Wrong input shape | Check tensor dimensions |
|
| 486 |
+
| `KeyError: 'melody'` | Wrong model for melody | Use musicgen-melody |
|
| 487 |
+
| `Sample rate mismatch` | Wrong audio format | Resample to model rate |
|
| 488 |
+
|
| 489 |
+
## Getting Help
|
| 490 |
+
|
| 491 |
+
1. **GitHub Issues**: https://github.com/facebookresearch/audiocraft/issues
|
| 492 |
+
2. **HuggingFace Forums**: https://discuss.huggingface.co
|
| 493 |
+
3. **Paper**: https://arxiv.org/abs/2306.05284
|
| 494 |
+
|
| 495 |
+
### Reporting Issues
|
| 496 |
+
|
| 497 |
+
Include:
|
| 498 |
+
- Python version
|
| 499 |
+
- PyTorch version
|
| 500 |
+
- CUDA version
|
| 501 |
+
- AudioCraft version: `pip show audiocraft`
|
| 502 |
+
- Full error traceback
|
| 503 |
+
- Minimal reproducible code
|
| 504 |
+
- Hardware (GPU model, VRAM)
|
optional-skills/creative/baoyu-article-illustrator/PORT_NOTES.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Port Notes — baoyu-article-illustrator
|
| 2 |
+
|
| 3 |
+
Ported from [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.57.0.
|
| 4 |
+
|
| 5 |
+
## Changes from upstream
|
| 6 |
+
|
| 7 |
+
`SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` were adapted. The 23 style files and 4 palette files are verbatim copies. The `references/config/` directory was removed entirely.
|
| 8 |
+
|
| 9 |
+
### Adaptations
|
| 10 |
+
|
| 11 |
+
| Change | Upstream | Hermes |
|
| 12 |
+
|--------|----------|--------|
|
| 13 |
+
| Metadata namespace | `openclaw` | `hermes` |
|
| 14 |
+
| Trigger | `/baoyu-article-illustrator` slash command + CLI flags | Natural language skill matching |
|
| 15 |
+
| User config | EXTEND.md (project/user/XDG paths) + first-time-setup | Removed — not part of Hermes infra |
|
| 16 |
+
| User prompts | `AskUserQuestion` (batched, multi-question) | `clarify` tool (one question at a time) |
|
| 17 |
+
| Image generation | `baoyu-imagine` (Bun/TypeScript, multi-provider, accepts `--ref`, writes to local path) | `image_generate` (returns URL only; agent downloads via `terminal`/`curl`) |
|
| 18 |
+
| Backend selection | User picks provider via CLI flags | Not agent-selectable — `image_generate` uses the user-configured FAL model. Removed hardcoded "nano banana pro" line from `prompts/system.md`. |
|
| 19 |
+
| Reference images | Passed to backend via `--ref`, copied via shell | `vision_analyze` extracts a textual description (binary never touched by `write_file`/`read_file`); description is embedded in prompts. Optional `terminal cp` for a local record. |
|
| 20 |
+
| Platform support | Linux/macOS/Windows/WSL/PowerShell | Linux/macOS only |
|
| 21 |
+
| File operations | Bash commands | Hermes file tools: `write_file`/`read_file` for text, `terminal` for binaries and URL downloads, `vision_analyze` for reading images |
|
| 22 |
+
| Watermark | Driven by EXTEND.md `watermark.enabled` | Optional — user asks for it per-article |
|
| 23 |
+
| Output directory | EXTEND.md `default_output_dir` (imgs-subdir / same-dir / illustrations-subdir / independent) | Defaults based on input type; user overrides in request |
|
| 24 |
+
|
| 25 |
+
### What was preserved
|
| 26 |
+
|
| 27 |
+
- Type × Style × Palette three-dimension framework
|
| 28 |
+
- All style definitions (23 files, verbatim)
|
| 29 |
+
- All palette definitions (4 files, verbatim)
|
| 30 |
+
- Core reference files (workflow, prompt-construction, styles, style-presets) — adapted for Hermes tooling
|
| 31 |
+
- Core principles and workflow structure (analyze → confirm → outline → prompts → generate)
|
| 32 |
+
- Prompt-file-as-reproducibility-record discipline
|
| 33 |
+
- Author, version, homepage attribution
|
| 34 |
+
|
| 35 |
+
## Syncing with upstream
|
| 36 |
+
|
| 37 |
+
To pull upstream updates:
|
| 38 |
+
|
| 39 |
+
```bash
|
| 40 |
+
# Compare versions
|
| 41 |
+
curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/SKILL.md | head -5
|
| 42 |
+
# Look for version: line
|
| 43 |
+
|
| 44 |
+
# Diff style/palette files (safe to overwrite — unchanged from upstream)
|
| 45 |
+
diff <(curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/references/styles/blueprint.md) references/styles/blueprint.md
|
| 46 |
+
```
|
| 47 |
+
|
| 48 |
+
`references/styles/*` and `references/palettes/*` can be overwritten directly. `SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` must be manually merged since they contain Hermes-specific adaptations (tool wiring, backend neutrality, removed EXTEND.md references).
|
optional-skills/creative/baoyu-article-illustrator/SKILL.md
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
name: baoyu-article-illustrator
|
| 3 |
+
description: "Article illustrations: type × style × palette consistency."
|
| 4 |
+
version: 1.57.0
|
| 5 |
+
author: 宝玉 (JimLiu)
|
| 6 |
+
license: MIT
|
| 7 |
+
platforms: [linux, macos, windows]
|
| 8 |
+
metadata:
|
| 9 |
+
hermes:
|
| 10 |
+
tags: [article-illustration, creative, image-generation]
|
| 11 |
+
category: creative
|
| 12 |
+
homepage: https://github.com/JimLiu/baoyu-skills#baoyu-article-illustrator
|
| 13 |
+
---
|
| 14 |
+
|
| 15 |
+
# Article Illustrator
|
| 16 |
+
|
| 17 |
+
Adapted from [baoyu-article-illustrator](https://github.com/JimLiu/baoyu-skills) for Hermes Agent's tool ecosystem.
|
| 18 |
+
|
| 19 |
+
Analyze articles, identify illustration positions, generate images with **Type × Style × Palette** consistency.
|
| 20 |
+
|
| 21 |
+
## When to Use
|
| 22 |
+
|
| 23 |
+
Trigger this skill when the user asks to illustrate an article, add images to an article, generate illustrations for content, or uses phrases like "为文章配图", "illustrate article", or "add images". The user provides an article (file path or pasted content) and optionally specifies type, style, palette, or density.
|
| 24 |
+
|
| 25 |
+
## Three Dimensions
|
| 26 |
+
|
| 27 |
+
| Dimension | Controls | Examples |
|
| 28 |
+
|-----------|----------|----------|
|
| 29 |
+
| **Type** | Information structure | infographic, scene, flowchart, comparison, framework, timeline |
|
| 30 |
+
| **Style** | Rendering approach | notion, warm, minimal, blueprint, watercolor, elegant |
|
| 31 |
+
| **Palette** | Color scheme (optional) | macaron, warm, neon — overrides style's default colors |
|
| 32 |
+
|
| 33 |
+
Combine freely: `type=infographic, style=vector-illustration, palette=macaron`.
|
| 34 |
+
|
| 35 |
+
Or use presets: `edu-visual` → type + style + palette in one shot. See [style-presets.md](references/style-presets.md).
|
| 36 |
+
|
| 37 |
+
## Types
|
| 38 |
+
|
| 39 |
+
| Type | Best For |
|
| 40 |
+
|------|----------|
|
| 41 |
+
| `infographic` | Data, metrics, technical |
|
| 42 |
+
| `scene` | Narratives, emotional |
|
| 43 |
+
| `flowchart` | Processes, workflows |
|
| 44 |
+
| `comparison` | Side-by-side, options |
|
| 45 |
+
| `framework` | Models, architecture |
|
| 46 |
+
| `timeline` | History, evolution |
|
| 47 |
+
|
| 48 |
+
## Styles
|
| 49 |
+
|
| 50 |
+
See [references/styles.md](references/styles.md) for Core Styles, the full gallery, and Type × Style compatibility.
|
| 51 |
+
|
| 52 |
+
## Output Structure
|
| 53 |
+
|
| 54 |
+
```
|
| 55 |
+
{output-dir}/
|
| 56 |
+
├── source-{slug}.{ext} # Only for pasted content
|
| 57 |
+
├── outline.md
|
| 58 |
+
├── prompts/
|
| 59 |
+
│ └── NN-{type}-{slug}.md
|
| 60 |
+
└── NN-{type}-{slug}.png
|
| 61 |
+
```
|
| 62 |
+
|
| 63 |
+
**Default output directory**:
|
| 64 |
+
|
| 65 |
+
| Input | Output Directory | Markdown Insert Path |
|
| 66 |
+
|-------|------------------|----------------------|
|
| 67 |
+
| Article file path | `{article-dir}/imgs/` | `imgs/NN-{type}-{slug}.png` |
|
| 68 |
+
| Pasted content | `illustrations/{topic-slug}/` (cwd) | `illustrations/{topic-slug}/NN-{type}-{slug}.png` |
|
| 69 |
+
|
| 70 |
+
If the user asks for a different layout (e.g., images alongside the article, or a `illustrations/` subdirectory), honor that.
|
| 71 |
+
|
| 72 |
+
**Slug**: 2-4 words, kebab-case. **Conflict**: append `-YYYYMMDD-HHMMSS`.
|
| 73 |
+
|
| 74 |
+
## Core Principles
|
| 75 |
+
|
| 76 |
+
- **Visualize concepts, not metaphors** — if the article uses a metaphor (e.g., "电锯切西瓜"), illustrate the underlying concept, not the literal image.
|
| 77 |
+
- **Labels use article data** — actual numbers, terms, and quotes from the article, not generic placeholders.
|
| 78 |
+
- **Prompt files are reproducibility records** — every illustration must have a saved prompt file under `prompts/` before any image is generated.
|
| 79 |
+
- **Strip secrets** — scan source content for API keys, tokens, or credentials before writing anything to disk.
|
| 80 |
+
|
| 81 |
+
## Workflow
|
| 82 |
+
|
| 83 |
+
```
|
| 84 |
+
- [ ] Step 1: Detect reference images (if provided)
|
| 85 |
+
- [ ] Step 2: Analyze content
|
| 86 |
+
- [ ] Step 3: Confirm settings (clarify tool, one question at a time)
|
| 87 |
+
- [ ] Step 4: Generate outline
|
| 88 |
+
- [ ] Step 5: Generate prompts
|
| 89 |
+
- [ ] Step 6: Generate images (image_generate)
|
| 90 |
+
- [ ] Step 7: Finalize
|
| 91 |
+
```
|
| 92 |
+
|
| 93 |
+
### Step 1: Detect Reference Images
|
| 94 |
+
|
| 95 |
+
If the user supplies reference images (paths pasted inline, attachments, or a URL):
|
| 96 |
+
|
| 97 |
+
1. For each reference, call `vision_analyze` with the path/URL and a question asking for style, palette, composition, and subject. Record the returned description in `{output-dir}/references/NN-ref-{slug}.md` via `write_file`.
|
| 98 |
+
2. **Do not** try to copy the binary via `write_file` / `read_file` — those are text-only. If you want a local copy for the record, use `terminal` (`cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"`). The skill itself never needs to read the binary; it works off the vision description.
|
| 99 |
+
3. Since `image_generate` doesn't take image inputs, the vision description is what gets embedded in prompts during Step 5.
|
| 100 |
+
|
| 101 |
+
Full procedures: [references/workflow.md](references/workflow.md#step-1-detect-reference-images).
|
| 102 |
+
|
| 103 |
+
### Step 2: Analyze
|
| 104 |
+
|
| 105 |
+
| Analysis | Output |
|
| 106 |
+
|----------|--------|
|
| 107 |
+
| Content type | Technical / Tutorial / Methodology / Narrative |
|
| 108 |
+
| Purpose | information / visualization / imagination |
|
| 109 |
+
| Core arguments | 2-5 main points |
|
| 110 |
+
| Positions | Where illustrations add value |
|
| 111 |
+
|
| 112 |
+
Read source (file path → `read_file`, or pasted text) and write the analysis to `{output-dir}/analysis.md` using `write_file`.
|
| 113 |
+
|
| 114 |
+
Full procedures: [references/workflow.md](references/workflow.md#step-2-analyze).
|
| 115 |
+
|
| 116 |
+
### Step 3: Confirm Settings
|
| 117 |
+
|
| 118 |
+
Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question whose answer is already present in the user's request.
|
| 119 |
+
|
| 120 |
+
| Order | Question | Options |
|
| 121 |
+
|-------|----------|---------|
|
| 122 |
+
| Q1 | **Preset or Type** | [Recommended preset], [alt preset], or manual: infographic, scene, flowchart, comparison, framework, timeline, mixed |
|
| 123 |
+
| Q2 | **Density** | minimal (1-2), balanced (3-5), per-section (Recommended), rich (6+) |
|
| 124 |
+
| Q3 | **Style** *(skip if preset chosen in Q1)* | [Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster |
|
| 125 |
+
| Q4 | **Palette** *(optional)* | Default (style colors), macaron, warm, neon |
|
| 126 |
+
| Q5 | **Language** *(only if article language is ambiguous)* | article language / user language |
|
| 127 |
+
|
| 128 |
+
Don't ask more than 2-3 `clarify` questions in a row. If the user already specified these in their request, skip entirely.
|
| 129 |
+
|
| 130 |
+
Full procedures: [references/workflow.md](references/workflow.md#step-3-confirm-settings).
|
| 131 |
+
|
| 132 |
+
### Step 4: Generate Outline → `outline.md`
|
| 133 |
+
|
| 134 |
+
Save `{output-dir}/outline.md` using `write_file` with frontmatter (type, density, style, palette, image_count) and one entry per illustration:
|
| 135 |
+
|
| 136 |
+
```yaml
|
| 137 |
+
## Illustration 1
|
| 138 |
+
**Position**: [section/paragraph]
|
| 139 |
+
**Purpose**: [why]
|
| 140 |
+
**Visual Content**: [what to show]
|
| 141 |
+
**Filename**: 01-infographic-concept-name.png
|
| 142 |
+
```
|
| 143 |
+
|
| 144 |
+
Full template: [references/workflow.md](references/workflow.md#step-4-generate-outline).
|
| 145 |
+
|
| 146 |
+
### Step 5: Generate Prompts
|
| 147 |
+
|
| 148 |
+
**BLOCKING**: Every illustration must have a saved prompt file before any image is generated — the prompt file is the reproducibility record.
|
| 149 |
+
|
| 150 |
+
For each illustration:
|
| 151 |
+
|
| 152 |
+
1. Create a prompt file per [references/prompt-construction.md](references/prompt-construction.md).
|
| 153 |
+
2. Save to `{output-dir}/prompts/NN-{type}-{slug}.md` using `write_file` with YAML frontmatter.
|
| 154 |
+
3. Prompts MUST use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT).
|
| 155 |
+
4. LABELS MUST include article-specific data: actual numbers, terms, metrics, quotes.
|
| 156 |
+
5. Process references (`direct`/`style`/`palette`) per prompt frontmatter — for `direct` usage, embed a textual description of the reference in the prompt (since `image_generate` doesn't take reference-image inputs).
|
| 157 |
+
|
| 158 |
+
### Step 6: Generate Images
|
| 159 |
+
|
| 160 |
+
For each prompt file:
|
| 161 |
+
|
| 162 |
+
1. Call `image_generate(prompt=..., aspect_ratio=...)`. `image_generate` returns a JSON result containing an image URL; it does NOT write to disk and does NOT accept an output path.
|
| 163 |
+
2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
|
| 164 |
+
3. Download the returned URL to `{output-dir}/NN-{type}-{slug}.png` via `terminal` (e.g. `curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{url}"`).
|
| 165 |
+
4. On generation failure, auto-retry once.
|
| 166 |
+
|
| 167 |
+
Note: the underlying image-generation backend is user-configured (default: FAL FLUX 2 Klein 9B) and is NOT agent-selectable via `image_generate`. Do not write model names into prompts expecting them to route.
|
| 168 |
+
|
| 169 |
+
### Step 7: Finalize
|
| 170 |
+
|
| 171 |
+
Insert `` after the corresponding paragraph. Alt text: concise description in the article's language.
|
| 172 |
+
|
| 173 |
+
Report:
|
| 174 |
+
|
| 175 |
+
```
|
| 176 |
+
Article Illustration Complete!
|
| 177 |
+
Article: [path] | Type: [type] | Density: [level] | Style: [style] | Palette: [palette or default]
|
| 178 |
+
Images: X/N generated
|
| 179 |
+
```
|
| 180 |
+
|
| 181 |
+
## Modification
|
| 182 |
+
|
| 183 |
+
| Action | Steps |
|
| 184 |
+
|--------|-------|
|
| 185 |
+
| Edit | Update prompt → Regenerate → Update reference |
|
| 186 |
+
| Add | Position → Prompt → Generate → Update outline → Insert |
|
| 187 |
+
| Delete | Delete files → Remove reference → Update outline |
|
| 188 |
+
|
| 189 |
+
## References
|
| 190 |
+
|
| 191 |
+
| File | Content |
|
| 192 |
+
|------|---------|
|
| 193 |
+
| [references/workflow.md](references/workflow.md) | Detailed procedures |
|
| 194 |
+
| [references/usage.md](references/usage.md) | Invocation examples |
|
| 195 |
+
| [references/styles.md](references/styles.md) | Style gallery + Palette gallery |
|
| 196 |
+
| [references/style-presets.md](references/style-presets.md) | Preset shortcuts (type + style + palette) |
|
| 197 |
+
| [references/prompt-construction.md](references/prompt-construction.md) | Prompt templates |
|
| 198 |
+
|
| 199 |
+
## Pitfalls
|
| 200 |
+
|
| 201 |
+
1. **Data integrity is paramount** — never summarize, paraphrase, or alter source statistics. "73% increase" stays "73% increase".
|
| 202 |
+
2. **Strip secrets** — scan source content for API keys, tokens, or credentials before including in any output file.
|
| 203 |
+
3. **Don't illustrate metaphors literally** — visualize the underlying concept.
|
| 204 |
+
4. **Prompt files are mandatory** — no image generation without a saved prompt file. The file is what lets you regenerate or switch backends later.
|
| 205 |
+
5. **`image_generate` aspect ratios** — the tool supports `landscape`, `portrait`, and `square`. Custom ratios map to the nearest option.
|
| 206 |
+
6. **`image_generate` returns a URL, not a local file** — always download via `terminal` (`curl`) before inserting local image paths into the article.
|
| 207 |
+
7. **No backend selection from the agent** — `image_generate` uses whatever model the user configured (default: FAL FLUX 2 Klein 9B). Don't write `"use <model> to generate this"` into prompts expecting it to route.
|
optional-skills/creative/baoyu-article-illustrator/prompts/system.md
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
Create a cartoon-style infographic illustration following these guidelines:
|
| 2 |
+
|
| 3 |
+
## Image Specifications
|
| 4 |
+
|
| 5 |
+
- **Type**: Infographic illustration
|
| 6 |
+
- **Orientation**: Landscape (horizontal)
|
| 7 |
+
- **Aspect Ratio**: 16:9
|
| 8 |
+
- **Style**: Hand-drawn illustration
|
| 9 |
+
|
| 10 |
+
## Core Principles
|
| 11 |
+
|
| 12 |
+
- Hand-drawn quality throughout - NO realistic or photographic elements
|
| 13 |
+
- If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
|
| 14 |
+
- Keep information concise, highlight keywords and core concepts
|
| 15 |
+
- Use ample whitespace for easy visual scanning
|
| 16 |
+
- Maintain clear visual hierarchy
|
| 17 |
+
|
| 18 |
+
## Text Style (When Text Included)
|
| 19 |
+
|
| 20 |
+
- **ALL text MUST be hand-drawn style**
|
| 21 |
+
- Text should be readable and complement the visual
|
| 22 |
+
- Font style harmonizes with illustration style
|
| 23 |
+
- **DO NOT use realistic or computer-generated fonts**
|
| 24 |
+
|
| 25 |
+
## Language
|
| 26 |
+
|
| 27 |
+
- Use the same language as the content provided below for any text elements
|
| 28 |
+
- Match punctuation style to the content language
|
| 29 |
+
|
| 30 |
+
---
|
| 31 |
+
|
| 32 |
+
Generate the illustration based on the content provided below:
|
optional-skills/creative/baoyu-article-illustrator/references/palettes/macaron.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# macaron
|
| 2 |
+
|
| 3 |
+
Soft macaron pastel color blocks on warm cream
|
| 4 |
+
|
| 5 |
+
## Background
|
| 6 |
+
|
| 7 |
+
- Color: Warm Cream (#F5F0E8)
|
| 8 |
+
- Texture: Subtle warm paper grain
|
| 9 |
+
|
| 10 |
+
## Colors
|
| 11 |
+
|
| 12 |
+
| Role | Color | Hex | Usage |
|
| 13 |
+
|------|-------|-----|-------|
|
| 14 |
+
| Background | Warm Cream | #F5F0E8 | Primary background |
|
| 15 |
+
| Primary Text | Deep Charcoal | #2D2D2D | Headlines, main text, outlines |
|
| 16 |
+
| Macaron Blue | Sky Blue | #A8D8EA | Info block fill, cool-toned zones |
|
| 17 |
+
| Macaron Mint | Mint Green | #B5E5CF | Info block fill, growth/positive zones |
|
| 18 |
+
| Macaron Lavender | Lavender | #D5C6E0 | Info block fill, abstract/concept zones |
|
| 19 |
+
| Macaron Peach | Peach | #FFD5C2 | Info block fill, warm-toned zones |
|
| 20 |
+
| Accent | Coral Red | #E8655A | Key data, warnings, emphasis |
|
| 21 |
+
| Muted Text | Warm Gray | #6B6B6B | Secondary annotations, small labels |
|
| 22 |
+
|
| 23 |
+
## Accent
|
| 24 |
+
|
| 25 |
+
Coral Red (#E8655A) for key data, warnings, and emphasis highlights. Use sparingly — one or two elements per illustration.
|
| 26 |
+
|
| 27 |
+
## Semantic Constraint
|
| 28 |
+
|
| 29 |
+
Soft pastel macaron color palette. Use block colors as rounded card backgrounds for distinct information sections. Accent coral red sparingly for emphasis on key terms only. Do NOT render color names, hex codes, or role labels as visible text in the image.
|
| 30 |
+
|
| 31 |
+
## Best For
|
| 32 |
+
|
| 33 |
+
Educational content, knowledge sharing, concept explainers, tutorials, tech summaries, onboarding materials
|
optional-skills/creative/baoyu-article-illustrator/references/palettes/mono-ink.md
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# mono-ink
|
| 2 |
+
|
| 3 |
+
Black ink on pure white with sparse semantic accent colors
|
| 4 |
+
|
| 5 |
+
## Background
|
| 6 |
+
|
| 7 |
+
- Color: Pure White (#FFFFFF)
|
| 8 |
+
- Texture: Clean, no grain, no tint
|
| 9 |
+
|
| 10 |
+
## Colors
|
| 11 |
+
|
| 12 |
+
| Role | Color | Hex | Usage |
|
| 13 |
+
|------|-------|-----|-------|
|
| 14 |
+
| Background | Pure White | #FFFFFF | Canvas |
|
| 15 |
+
| Primary | Near Black | #1A1A1A | All lines, text, figures, arrows |
|
| 16 |
+
| Accent (risk/emphasis) | Coral Red | #E8655A | Risk, problem, gap, key emphasis |
|
| 17 |
+
| Accent (positive) | Muted Teal | #5FA8A8 | Positive, solution, "after" state |
|
| 18 |
+
| Accent (neutral tag) | Dusty Lavender | #9B8AB5 | Neutral tags, category labels |
|
| 19 |
+
| Soft Fill | Pale Gray | #F0F0F0 | Subtle zone backgrounds (optional) |
|
| 20 |
+
|
| 21 |
+
## Accent
|
| 22 |
+
|
| 23 |
+
Use black ink for all structural elements — lines, text, figures. Accent colors appear only for semantic highlighting: coral red for risks/gaps/problems, muted teal for positive/solution/after-states, dusty lavender for neutral category tags. Total colored pixels must remain under 10% of canvas. Pale gray may back a subtle zone but must never dominate.
|
| 24 |
+
|
| 25 |
+
## Semantic Constraint
|
| 26 |
+
|
| 27 |
+
Black ink on white canvas. Accent colors for semantic highlighting only — total colored pixels under 10% of canvas. Do NOT render color names, hex codes, or role labels as visible text in the image.
|
| 28 |
+
|
| 29 |
+
## Compatible With
|
| 30 |
+
|
| 31 |
+
- `ink-notes` (primary, default pairing)
|
| 32 |
+
- `minimal` (strict monochrome variation, drops the style's built-in accent)
|
| 33 |
+
- `sketch` (pencil + ink hybrid look)
|
| 34 |
+
|
| 35 |
+
## Not Recommended With
|
| 36 |
+
|
| 37 |
+
- `sketch-notes` — its "no pure white backgrounds" rule conflicts
|
| 38 |
+
- `warm`, `elegant`, `watercolor`, `fantasy-animation` — color-heavy by design, mono-ink strips their identity
|
| 39 |
+
|
| 40 |
+
## Best For
|
| 41 |
+
|
| 42 |
+
Professional visual notes, Before/After essays, tech manifestos, framework analogies, whiteboard-presentation explainers
|
optional-skills/creative/baoyu-article-illustrator/references/palettes/neon.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# neon
|
| 2 |
+
|
| 3 |
+
Vibrant neon colors on dark backgrounds
|
| 4 |
+
|
| 5 |
+
## Background
|
| 6 |
+
|
| 7 |
+
- Color: Deep Purple (#2D1B4E)
|
| 8 |
+
- Texture: Subtle grid pattern or solid dark
|
| 9 |
+
|
| 10 |
+
## Colors
|
| 11 |
+
|
| 12 |
+
| Role | Color | Hex | Usage |
|
| 13 |
+
|------|-------|-----|-------|
|
| 14 |
+
| Background | Deep Purple | #2D1B4E | Primary background |
|
| 15 |
+
| Alt Background | Dark Teal | #0F4C5C | Alternative sections |
|
| 16 |
+
| Primary | Hot Pink | #FF1493 | Main accent |
|
| 17 |
+
| Secondary | Electric Cyan | #00FFFF | Supporting elements |
|
| 18 |
+
| Tertiary | Neon Yellow | #FFFF00 | Highlights |
|
| 19 |
+
| Accent 1 | Lime Green | #32CD32 | Energy, success |
|
| 20 |
+
| Accent 2 | Orange | #FF6B35 | Warmth |
|
| 21 |
+
| Text | White | #FFFFFF | Text elements |
|
| 22 |
+
|
| 23 |
+
## Accent
|
| 24 |
+
|
| 25 |
+
Hot Pink (#FF1493) for primary emphasis. High contrast neon-on-dark creates immediate visual impact.
|
| 26 |
+
|
| 27 |
+
## Semantic Constraint
|
| 28 |
+
|
| 29 |
+
Vibrant neon-on-dark palette. High contrast, immediate visual impact. Do NOT render color names, hex codes, or role labels as visible text in the image.
|
| 30 |
+
|
| 31 |
+
## Best For
|
| 32 |
+
|
| 33 |
+
Gaming, retro tech, 80s/90s nostalgic content, bold editorial, trend and pop culture
|
optional-skills/creative/baoyu-article-illustrator/references/palettes/warm.md
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# warm
|
| 2 |
+
|
| 3 |
+
Warm earth tones on soft peach, no cool colors
|
| 4 |
+
|
| 5 |
+
## Background
|
| 6 |
+
|
| 7 |
+
- Color: Soft Peach (#FFECD2)
|
| 8 |
+
- Texture: Warm paper texture
|
| 9 |
+
|
| 10 |
+
## Colors
|
| 11 |
+
|
| 12 |
+
| Role | Color | Hex | Usage |
|
| 13 |
+
|------|-------|-----|-------|
|
| 14 |
+
| Background | Soft Peach | #FFECD2 | Primary background |
|
| 15 |
+
| Outlines | Deep Charcoal | #2D2D2D | All element outlines |
|
| 16 |
+
| Primary | Warm Orange | #ED8936 | Main accent color |
|
| 17 |
+
| Secondary | Terracotta | #C05621 | Warm depth |
|
| 18 |
+
| Tertiary | Golden Yellow | #F6AD55 | Highlights, energy |
|
| 19 |
+
| Accent | Deep Brown | #744210 | Grounding, anchoring |
|
| 20 |
+
| Text | Warm Charcoal | #4A4A4A | Text elements |
|
| 21 |
+
|
| 22 |
+
## Accent
|
| 23 |
+
|
| 24 |
+
Warm Orange (#ED8936) for primary emphasis. Warm-only palette — no cool colors (no green, blue, purple). Modern-retro feel.
|
| 25 |
+
|
| 26 |
+
## Semantic Constraint
|
| 27 |
+
|
| 28 |
+
Warm earth tone palette. Warm-only — no cool colors (no green, blue, purple). Do NOT render color names, hex codes, or role labels as visible text in the image.
|
| 29 |
+
|
| 30 |
+
## Best For
|
| 31 |
+
|
| 32 |
+
Product showcases, team introductions, feature grids, brand content, personal growth, lifestyle
|
optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md
ADDED
|
@@ -0,0 +1,426 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Prompt Construction
|
| 2 |
+
|
| 3 |
+
## Prompt File Format
|
| 4 |
+
|
| 5 |
+
Each prompt file uses YAML frontmatter + content:
|
| 6 |
+
|
| 7 |
+
```yaml
|
| 8 |
+
---
|
| 9 |
+
illustration_id: 01
|
| 10 |
+
type: infographic
|
| 11 |
+
style: blueprint
|
| 12 |
+
references: # ⚠️ ONLY if files EXIST in references/ directory
|
| 13 |
+
- ref_id: 01
|
| 14 |
+
filename: 01-ref-diagram.png
|
| 15 |
+
usage: direct # direct | style | palette
|
| 16 |
+
---
|
| 17 |
+
|
| 18 |
+
[Type-specific template content below...]
|
| 19 |
+
```
|
| 20 |
+
|
| 21 |
+
**⚠️ CRITICAL - When to include `references` field**:
|
| 22 |
+
|
| 23 |
+
| Situation | Action |
|
| 24 |
+
|-----------|--------|
|
| 25 |
+
| Reference file saved to `references/` | Include in frontmatter ✓ |
|
| 26 |
+
| Style extracted verbally (no file) | DO NOT include in frontmatter, append to prompt body instead |
|
| 27 |
+
| File path in frontmatter but file doesn't exist | ERROR - remove references field |
|
| 28 |
+
|
| 29 |
+
**Reference Usage Types** (only when file exists):
|
| 30 |
+
|
| 31 |
+
| Usage | Description | Generation Action |
|
| 32 |
+
|-------|-------------|-------------------|
|
| 33 |
+
| `direct` | Primary visual reference | Describe the reference (composition, subject, style, palette) in prompt text — `image_generate` does not accept reference-image inputs |
|
| 34 |
+
| `style` | Style characteristics only | Describe style in prompt text |
|
| 35 |
+
| `palette` | Color palette extraction | Include colors in prompt |
|
| 36 |
+
|
| 37 |
+
**If no reference file but style/palette extracted verbally**, append directly to prompt body:
|
| 38 |
+
```
|
| 39 |
+
COLORS (from reference):
|
| 40 |
+
- Primary: #E8756D coral
|
| 41 |
+
- Secondary: #7ECFC0 mint
|
| 42 |
+
...
|
| 43 |
+
|
| 44 |
+
STYLE (from reference):
|
| 45 |
+
- Clean lines, minimal shadows
|
| 46 |
+
- Gradient backgrounds
|
| 47 |
+
...
|
| 48 |
+
```
|
| 49 |
+
|
| 50 |
+
---
|
| 51 |
+
|
| 52 |
+
## Default Composition Requirements
|
| 53 |
+
|
| 54 |
+
**Apply to ALL prompts by default**:
|
| 55 |
+
|
| 56 |
+
| Requirement | Description |
|
| 57 |
+
|-------------|-------------|
|
| 58 |
+
| **Clean composition** | Simple layouts, no visual clutter |
|
| 59 |
+
| **White space** | Generous margins, breathing room around elements |
|
| 60 |
+
| **No complex backgrounds** | Solid colors or subtle gradients only, avoid busy textures |
|
| 61 |
+
| **Centered or content-appropriate** | Main visual elements centered or positioned by content needs |
|
| 62 |
+
| **Matching graphics** | Use graphic elements that align with content theme |
|
| 63 |
+
| **Highlight core info** | White space draws attention to key information |
|
| 64 |
+
|
| 65 |
+
**Add to ALL prompts**:
|
| 66 |
+
> Clean composition with generous white space. Simple or no background. Main elements centered or positioned by content needs.
|
| 67 |
+
|
| 68 |
+
---
|
| 69 |
+
|
| 70 |
+
## Color Specification Rules
|
| 71 |
+
|
| 72 |
+
Colors in prompts use hex codes for **rendering guidance only** — they tell the model which colors to use, NOT what text to display.
|
| 73 |
+
|
| 74 |
+
**⚠️ CRITICAL**: Image generation models sometimes render color names and hex values as visible text labels in the image (e.g., painting "Macaron Blue #A8D8EA" as a label). This must be prevented.
|
| 75 |
+
|
| 76 |
+
**Add to ALL prompts that contain a COLORS section**:
|
| 77 |
+
> Color values (#hex) and color names are rendering guidance only — do NOT display color names, hex codes, or palette labels as visible text in the image.
|
| 78 |
+
|
| 79 |
+
---
|
| 80 |
+
|
| 81 |
+
## Character Rendering
|
| 82 |
+
|
| 83 |
+
When depicting people:
|
| 84 |
+
|
| 85 |
+
| Guideline | Description |
|
| 86 |
+
|-----------|-------------|
|
| 87 |
+
| **Style** | Simplified cartoon silhouettes or symbolic expressions |
|
| 88 |
+
| **Avoid** | Realistic human portrayals, detailed faces |
|
| 89 |
+
| **Diversity** | Varied body types when showing multiple people |
|
| 90 |
+
| **Emotion** | Express through posture and simple gestures |
|
| 91 |
+
|
| 92 |
+
**Add to ALL prompts with human figures**:
|
| 93 |
+
> Human figures: simplified stylized silhouettes or symbolic representations, not photorealistic.
|
| 94 |
+
|
| 95 |
+
---
|
| 96 |
+
|
| 97 |
+
## Text in Illustrations
|
| 98 |
+
|
| 99 |
+
| Element | Guideline |
|
| 100 |
+
|---------|-----------|
|
| 101 |
+
| **Size** | Large, prominent, immediately readable |
|
| 102 |
+
| **Style** | Handwritten fonts preferred for warmth |
|
| 103 |
+
| **Content** | Concise keywords and core concepts only |
|
| 104 |
+
| **Language** | Match article language |
|
| 105 |
+
|
| 106 |
+
**Add to prompts with text**:
|
| 107 |
+
> Text should be large and prominent with handwritten-style fonts. Keep minimal, focus on keywords.
|
| 108 |
+
|
| 109 |
+
---
|
| 110 |
+
|
| 111 |
+
## Principles
|
| 112 |
+
|
| 113 |
+
Good prompts must include:
|
| 114 |
+
|
| 115 |
+
1. **Layout Structure First**: Describe composition, zones, flow direction
|
| 116 |
+
2. **Specific Data/Labels**: Use actual numbers, terms from article
|
| 117 |
+
3. **Visual Relationships**: How elements connect
|
| 118 |
+
4. **Semantic Colors**: Meaning-based color choices (red=warning, green=efficient)
|
| 119 |
+
5. **Style Characteristics**: Line treatment, texture, mood
|
| 120 |
+
6. **Aspect Ratio**: End with ratio and complexity level
|
| 121 |
+
|
| 122 |
+
## Type-Specific Templates
|
| 123 |
+
|
| 124 |
+
### Infographic
|
| 125 |
+
|
| 126 |
+
```
|
| 127 |
+
[Title] - Data Visualization
|
| 128 |
+
|
| 129 |
+
Layout: [grid/radial/hierarchical]
|
| 130 |
+
|
| 131 |
+
ZONES:
|
| 132 |
+
- Zone 1: [data point with specific values]
|
| 133 |
+
- Zone 2: [comparison with metrics]
|
| 134 |
+
- Zone 3: [summary/conclusion]
|
| 135 |
+
|
| 136 |
+
LABELS: [specific numbers, percentages, terms from article]
|
| 137 |
+
COLORS: [semantic color mapping]
|
| 138 |
+
STYLE: [style characteristics]
|
| 139 |
+
ASPECT: 16:9
|
| 140 |
+
```
|
| 141 |
+
|
| 142 |
+
**Infographic + vector-illustration**:
|
| 143 |
+
```
|
| 144 |
+
Flat vector illustration infographic. Clean black outlines on all elements.
|
| 145 |
+
COLORS: Cream background (#F5F0E6), Coral Red (#E07A5F), Mint Green (#81B29A), Mustard Yellow (#F2CC8F)
|
| 146 |
+
ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements (dots, stars)
|
| 147 |
+
```
|
| 148 |
+
|
| 149 |
+
**Infographic + vector-illustration + warm palette**:
|
| 150 |
+
```
|
| 151 |
+
Flat vector illustration infographic. Clean black outlines on all elements.
|
| 152 |
+
PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
|
| 153 |
+
COLORS: Soft Peach background (#FFECD2), Warm Orange (#ED8936),
|
| 154 |
+
Terracotta (#C05621), Golden Yellow (#F6AD55), Deep Brown (#744210)
|
| 155 |
+
ELEMENTS: Geometric simplified icons, no gradients, rounded corners,
|
| 156 |
+
modular card layout, consistent icon style
|
| 157 |
+
```
|
| 158 |
+
|
| 159 |
+
### Scene
|
| 160 |
+
|
| 161 |
+
```
|
| 162 |
+
[Title] - Atmospheric Scene
|
| 163 |
+
|
| 164 |
+
FOCAL POINT: [main subject]
|
| 165 |
+
ATMOSPHERE: [lighting, mood, environment]
|
| 166 |
+
MOOD: [emotion to convey]
|
| 167 |
+
COLOR TEMPERATURE: [warm/cool/neutral]
|
| 168 |
+
STYLE: [style characteristics]
|
| 169 |
+
ASPECT: 16:9
|
| 170 |
+
```
|
| 171 |
+
|
| 172 |
+
### Flowchart
|
| 173 |
+
|
| 174 |
+
```
|
| 175 |
+
[Title] - Process Flow
|
| 176 |
+
|
| 177 |
+
Layout: [left-right/top-down/circular]
|
| 178 |
+
|
| 179 |
+
STEPS:
|
| 180 |
+
1. [Step name] - [brief description]
|
| 181 |
+
2. [Step name] - [brief description]
|
| 182 |
+
...
|
| 183 |
+
|
| 184 |
+
CONNECTIONS: [arrow types, decision points]
|
| 185 |
+
STYLE: [style characteristics]
|
| 186 |
+
ASPECT: 16:9
|
| 187 |
+
```
|
| 188 |
+
|
| 189 |
+
**Flowchart + vector-illustration**:
|
| 190 |
+
```
|
| 191 |
+
Flat vector flowchart with bold arrows and geometric step containers.
|
| 192 |
+
COLORS: Cream background (#F5F0E6), steps in Coral/Mint/Mustard, black outlines
|
| 193 |
+
ELEMENTS: Rounded rectangles, thick arrows, simple icons per step
|
| 194 |
+
```
|
| 195 |
+
|
| 196 |
+
**Flowchart + sketch-notes + macaron palette**:
|
| 197 |
+
```
|
| 198 |
+
Hand-drawn educational flowchart on warm cream paper. Slight wobble on all lines.
|
| 199 |
+
PALETTE: macaron — soft pastel color blocks
|
| 200 |
+
COLORS: Warm Cream background (#F5F0E8), zone fills in Macaron Blue (#A8D8EA),
|
| 201 |
+
Lavender (#D5C6E0), Mint (#B5E5CF), Coral Red (#E8655A) for emphasis
|
| 202 |
+
ELEMENTS: Rounded cards with dashed/solid borders, wavy hand-drawn arrows with labels,
|
| 203 |
+
simple stick-figure characters, doodle decorations (stars, underlines)
|
| 204 |
+
STYLE: Color fills don't completely fill outlines, hand-drawn lettering, generous white space
|
| 205 |
+
```
|
| 206 |
+
|
| 207 |
+
**Flowchart + ink-notes + mono-ink palette**:
|
| 208 |
+
```
|
| 209 |
+
Professional hand-drawn visual-note flowchart on pure white. Black ink line work
|
| 210 |
+
with slight wobble, à la Mike Rohde sketchnoting.
|
| 211 |
+
PALETTE: mono-ink — black ink dominant, sparse semantic accents
|
| 212 |
+
COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines,
|
| 213 |
+
text, and figures; Coral Red (#E8655A) only for risk/emphasis,
|
| 214 |
+
Muted Teal (#5FA8A8) only for positive/solution states
|
| 215 |
+
ELEMENTS: Left-to-right stage boxes with rounded-rect frames, wavy hand-drawn
|
| 216 |
+
arrows between stages, simple stick-figure characters with role
|
| 217 |
+
labels above (e.g., "ML Engineer", "Team Lead"), dashed-border box
|
| 218 |
+
for future/empty stage, small doodle icons per stage
|
| 219 |
+
STYLE: Hand-lettered titles (bold, oversized), handwritten stage labels and
|
| 220 |
+
annotations, generous white space, bottom tagline summarizing takeaway
|
| 221 |
+
```
|
| 222 |
+
|
| 223 |
+
### Comparison
|
| 224 |
+
|
| 225 |
+
```
|
| 226 |
+
[Title] - Comparison View
|
| 227 |
+
|
| 228 |
+
LEFT SIDE - [Option A]:
|
| 229 |
+
- [Point 1]
|
| 230 |
+
- [Point 2]
|
| 231 |
+
|
| 232 |
+
RIGHT SIDE - [Option B]:
|
| 233 |
+
- [Point 1]
|
| 234 |
+
- [Point 2]
|
| 235 |
+
|
| 236 |
+
DIVIDER: [visual separator]
|
| 237 |
+
STYLE: [style characteristics]
|
| 238 |
+
ASPECT: 16:9
|
| 239 |
+
```
|
| 240 |
+
|
| 241 |
+
**Comparison + vector-illustration**:
|
| 242 |
+
```
|
| 243 |
+
Flat vector comparison with split layout. Clear visual separation.
|
| 244 |
+
COLORS: Left side Coral (#E07A5F), Right side Mint (#81B29A), cream background
|
| 245 |
+
ELEMENTS: Bold icons, black outlines, centered divider line
|
| 246 |
+
```
|
| 247 |
+
|
| 248 |
+
**Comparison + vector-illustration + warm palette**:
|
| 249 |
+
```
|
| 250 |
+
Flat vector comparison with split layout. Clear visual separation.
|
| 251 |
+
PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
|
| 252 |
+
COLORS: Left side Warm Orange (#ED8936), Right side Terracotta (#C05621),
|
| 253 |
+
Soft Peach background (#FFECD2), Deep Brown (#744210) accents
|
| 254 |
+
ELEMENTS: Bold icons, black outlines, centered divider line
|
| 255 |
+
```
|
| 256 |
+
|
| 257 |
+
**Comparison + ink-notes + mono-ink palette** (Before/After, Traditional vs New):
|
| 258 |
+
```
|
| 259 |
+
Professional hand-drawn sketchnote comparison on pure white. Black ink line work
|
| 260 |
+
with slight wobble, à la Mike Rohde sketchnoting.
|
| 261 |
+
PALETTE: mono-ink — black ink dominant, sparse semantic accents
|
| 262 |
+
COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all outlines,
|
| 263 |
+
text, figures, arrows; Coral Red (#E8655A) reserved for risks/gaps
|
| 264 |
+
(left/Before side); Muted Teal (#5FA8A8) reserved for positives
|
| 265 |
+
(right/After side). Color accents under 10% of canvas.
|
| 266 |
+
LAYOUT: Left | Right split with vertical hand-drawn divider. Hand-lettered
|
| 267 |
+
"Before" label (top-left) and "After" label (top-right).
|
| 268 |
+
LEFT SIDE: Stick figure(s) with role label above, speech bubble showing the
|
| 269 |
+
pain point, bulleted pain-point list in handwritten text.
|
| 270 |
+
RIGHT SIDE: Stick figure(s) showing the new state, bulleted improvement list,
|
| 271 |
+
small positive-action icons.
|
| 272 |
+
BRIDGE: Curved hand-drawn "mindset shift" arrow bridging left → right with
|
| 273 |
+
small inline label describing the shift.
|
| 274 |
+
BOTTOM: Single-line hand-lettered tagline summarizing the takeaway.
|
| 275 |
+
STYLE: Hand-lettered headings (bold, oversized), handwritten body annotations,
|
| 276 |
+
generous white space, no computer fonts, no gradients, no shadows.
|
| 277 |
+
```
|
| 278 |
+
|
| 279 |
+
### Framework
|
| 280 |
+
|
| 281 |
+
```
|
| 282 |
+
[Title] - Conceptual Framework
|
| 283 |
+
|
| 284 |
+
STRUCTURE: [hierarchical/network/matrix]
|
| 285 |
+
|
| 286 |
+
NODES:
|
| 287 |
+
- [Concept 1] - [role]
|
| 288 |
+
- [Concept 2] - [role]
|
| 289 |
+
|
| 290 |
+
RELATIONSHIPS: [how nodes connect]
|
| 291 |
+
STYLE: [style characteristics]
|
| 292 |
+
ASPECT: 16:9
|
| 293 |
+
```
|
| 294 |
+
|
| 295 |
+
**Framework + vector-illustration**:
|
| 296 |
+
```
|
| 297 |
+
Flat vector framework diagram with geometric nodes and bold connectors.
|
| 298 |
+
COLORS: Cream background (#F5F0E6), nodes in Coral/Mint/Mustard/Blue, black outlines
|
| 299 |
+
ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines
|
| 300 |
+
```
|
| 301 |
+
|
| 302 |
+
**Framework + vector-illustration + warm palette**:
|
| 303 |
+
```
|
| 304 |
+
Flat vector framework diagram with geometric nodes and bold connectors.
|
| 305 |
+
PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
|
| 306 |
+
COLORS: Soft Peach background (#FFECD2), nodes in Warm Orange (#ED8936),
|
| 307 |
+
Terracotta (#C05621), Golden Yellow (#F6AD55), black outlines
|
| 308 |
+
ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines
|
| 309 |
+
```
|
| 310 |
+
|
| 311 |
+
**Framework + ink-notes + mono-ink palette** (command center, OS analogy):
|
| 312 |
+
```
|
| 313 |
+
Professional hand-drawn sketchnote framework on pure white. Black ink line work
|
| 314 |
+
with slight wobble, à la Mike Rohde sketchnoting.
|
| 315 |
+
PALETTE: mono-ink — black ink dominant, sparse semantic accents
|
| 316 |
+
COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines,
|
| 317 |
+
text, figures; Dusty Lavender (#9B8AB5) for neutral category tags only;
|
| 318 |
+
Coral Red (#E8655A) for emphasis sparingly. Color accents under 10%.
|
| 319 |
+
STRUCTURE: Central rounded-rectangle frame as "the system" with hand-lettered
|
| 320 |
+
title inside. Inner layer of labeled sub-components (node labels
|
| 321 |
+
above each). Outer layer of feeder arrows from stick-figure
|
| 322 |
+
operators/users with role labels.
|
| 323 |
+
ELEMENTS: Stick figures at the edges with role tags ("Team Lead", "Operator"),
|
| 324 |
+
wavy hand-drawn connector arrows with small inline labels, small
|
| 325 |
+
doodle icons per component, dashed-border placeholder(s) for
|
| 326 |
+
future/empty capabilities.
|
| 327 |
+
BOTTOM: Single-line hand-lettered tagline.
|
| 328 |
+
STYLE: Hand-lettered headings, handwritten annotations, generous white space,
|
| 329 |
+
no computer fonts, no gradients.
|
| 330 |
+
```
|
| 331 |
+
|
| 332 |
+
### Timeline
|
| 333 |
+
|
| 334 |
+
```
|
| 335 |
+
[Title] - Chronological View
|
| 336 |
+
|
| 337 |
+
DIRECTION: [horizontal/vertical]
|
| 338 |
+
|
| 339 |
+
EVENTS:
|
| 340 |
+
- [Date/Period 1]: [milestone]
|
| 341 |
+
- [Date/Period 2]: [milestone]
|
| 342 |
+
|
| 343 |
+
MARKERS: [visual indicators]
|
| 344 |
+
STYLE: [style characteristics]
|
| 345 |
+
ASPECT: 16:9
|
| 346 |
+
```
|
| 347 |
+
|
| 348 |
+
### Screen-Print Style Override
|
| 349 |
+
|
| 350 |
+
When `style: screen-print`, replace standard style instructions with:
|
| 351 |
+
|
| 352 |
+
```
|
| 353 |
+
Screen print / silkscreen poster art. Flat color blocks, NO gradients.
|
| 354 |
+
COLORS: 2-5 colors maximum. [Choose from style palette or duotone pair]
|
| 355 |
+
TEXTURE: Halftone dot patterns, slight color layer misregistration, paper grain
|
| 356 |
+
COMPOSITION: Bold silhouettes, geometric framing, negative space as storytelling element
|
| 357 |
+
FIGURES: Silhouettes only, no detailed faces, stencil-cut edges
|
| 358 |
+
TYPOGRAPHY: Bold condensed sans-serif integrated into composition (not overlaid)
|
| 359 |
+
```
|
| 360 |
+
|
| 361 |
+
**Scene + screen-print**:
|
| 362 |
+
```
|
| 363 |
+
Conceptual poster scene. Single symbolic focal point, NOT literal illustration.
|
| 364 |
+
COLORS: Duotone pair (e.g., Burnt Orange #E8751A + Deep Teal #0A6E6E) on Off-Black #121212
|
| 365 |
+
COMPOSITION: Centered silhouette or geometric frame, 60%+ negative space
|
| 366 |
+
TEXTURE: Halftone dots, paper grain, slight print misregistration
|
| 367 |
+
```
|
| 368 |
+
|
| 369 |
+
**Comparison + screen-print**:
|
| 370 |
+
```
|
| 371 |
+
Split poster composition. Each side dominated by one color from duotone pair.
|
| 372 |
+
LEFT: [Color A] side with silhouette/icon for [Option A]
|
| 373 |
+
RIGHT: [Color B] side with silhouette/icon for [Option B]
|
| 374 |
+
DIVIDER: Geometric shape or negative space boundary
|
| 375 |
+
TEXTURE: Halftone transitions between sides
|
| 376 |
+
```
|
| 377 |
+
|
| 378 |
+
---
|
| 379 |
+
|
| 380 |
+
## Palette Override
|
| 381 |
+
|
| 382 |
+
When a palette is specified (via `--palette` or preset), it overrides the style's default colors:
|
| 383 |
+
|
| 384 |
+
1. Read style file → get rendering rules (Visual Elements, Style Rules, line treatment)
|
| 385 |
+
2. Read palette file (`palettes/<palette>.md`) → get Colors + Background
|
| 386 |
+
3. Palette Colors **replace** style's default Color Palette in prompt
|
| 387 |
+
4. Palette Background **replaces** style's Background color (keep style's texture description)
|
| 388 |
+
5. Build prompt: style rendering instructions + palette colors
|
| 389 |
+
|
| 390 |
+
**Prompt frontmatter** includes palette when specified:
|
| 391 |
+
```yaml
|
| 392 |
+
---
|
| 393 |
+
illustration_id: 01
|
| 394 |
+
type: infographic
|
| 395 |
+
style: vector-illustration
|
| 396 |
+
palette: macaron
|
| 397 |
+
---
|
| 398 |
+
```
|
| 399 |
+
|
| 400 |
+
**Example**: `vector-illustration` + `macaron` palette:
|
| 401 |
+
```
|
| 402 |
+
Flat vector illustration infographic. Clean black outlines on all elements.
|
| 403 |
+
PALETTE: macaron — soft pastel color blocks
|
| 404 |
+
COLORS: Warm Cream background (#F5F0E8), Macaron Blue (#A8D8EA), Mint (#B5E5CF),
|
| 405 |
+
Lavender (#D5C6E0), Peach (#FFD5C2), Coral Red (#E8655A) for emphasis
|
| 406 |
+
ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements
|
| 407 |
+
```
|
| 408 |
+
|
| 409 |
+
When no palette is specified, use the style's built-in Color Palette as before.
|
| 410 |
+
|
| 411 |
+
---
|
| 412 |
+
|
| 413 |
+
## What to Avoid
|
| 414 |
+
|
| 415 |
+
- Vague descriptions ("a nice image")
|
| 416 |
+
- Literal metaphor illustrations
|
| 417 |
+
- Missing concrete labels/annotations
|
| 418 |
+
- Generic decorative elements
|
| 419 |
+
|
| 420 |
+
## Watermark Integration (optional)
|
| 421 |
+
|
| 422 |
+
If the user asks for a watermark, append:
|
| 423 |
+
|
| 424 |
+
```
|
| 425 |
+
Include a subtle watermark "[content]" positioned at [position].
|
| 426 |
+
```
|
optional-skills/creative/baoyu-article-illustrator/references/style-presets.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Style Presets
|
| 2 |
+
|
| 3 |
+
A preset expands to a type + style + optional palette combination. Users can override any dimension in their request.
|
| 4 |
+
|
| 5 |
+
## By Category
|
| 6 |
+
|
| 7 |
+
### Technical & Engineering
|
| 8 |
+
|
| 9 |
+
| Preset | Type | Style | Palette | Best For |
|
| 10 |
+
|----------|------|-------|---------|----------|
|
| 11 |
+
| `tech-explainer` | `infographic` | `blueprint` | — | API docs, system metrics, technical deep-dives |
|
| 12 |
+
| `system-design` | `framework` | `blueprint` | — | Architecture diagrams, system design |
|
| 13 |
+
| `architecture` | `framework` | `vector-illustration` | — | Component relationships, module structure |
|
| 14 |
+
| `science-paper` | `infographic` | `scientific` | — | Research findings, lab results, academic |
|
| 15 |
+
|
| 16 |
+
### Knowledge & Education
|
| 17 |
+
|
| 18 |
+
| Preset | Type | Style | Palette | Best For |
|
| 19 |
+
|----------|------|-------|---------|----------|
|
| 20 |
+
| `knowledge-base` | `infographic` | `vector-illustration` | — | Concept explainers, tutorials, how-to |
|
| 21 |
+
| `saas-guide` | `infographic` | `notion` | — | Product guides, SaaS docs, tool walkthroughs |
|
| 22 |
+
| `tutorial` | `flowchart` | `vector-illustration` | — | Step-by-step tutorials, setup guides |
|
| 23 |
+
| `process-flow` | `flowchart` | `notion` | — | Workflow documentation, onboarding flows |
|
| 24 |
+
| `warm-knowledge` | `infographic` | `vector-illustration` | `warm` | Product showcases, team intros, feature cards, brand content |
|
| 25 |
+
| `edu-visual` | `infographic` | `vector-illustration` | `macaron` | Knowledge summaries, concept explainers, educational articles |
|
| 26 |
+
| `hand-drawn-edu` | `flowchart` | `sketch-notes` | `macaron` | Hand-drawn educational diagrams, process explainers, onboarding visuals |
|
| 27 |
+
| `ink-notes-compare` | `comparison` | `ink-notes` | `mono-ink` | Before/After essays, Traditional vs New, OS-style comparisons, mindset-shift narratives |
|
| 28 |
+
| `ink-notes-flow` | `flowchart` | `ink-notes` | `mono-ink` | Professional process explainers, workforce pipelines, hand-drawn technical walkthroughs |
|
| 29 |
+
| `ink-notes-framework` | `framework` | `ink-notes` | `mono-ink` | System analogies, command-center diagrams, architecture-as-metaphor, tech manifestos |
|
| 30 |
+
|
| 31 |
+
### Data & Analysis
|
| 32 |
+
|
| 33 |
+
| Preset | Type | Style | Palette | Best For |
|
| 34 |
+
|----------|------|-------|---------|----------|
|
| 35 |
+
| `data-report` | `infographic` | `editorial` | — | Data journalism, metrics reports, dashboards |
|
| 36 |
+
| `versus` | `comparison` | `vector-illustration` | — | Tech comparisons, framework shootouts |
|
| 37 |
+
| `business-compare` | `comparison` | `elegant` | — | Product evaluations, strategy options |
|
| 38 |
+
|
| 39 |
+
### Narrative & Creative
|
| 40 |
+
|
| 41 |
+
| Preset | Type | Style | Palette | Best For |
|
| 42 |
+
|----------|------|-------|---------|----------|
|
| 43 |
+
| `storytelling` | `scene` | `warm` | — | Personal essays, reflections, growth stories |
|
| 44 |
+
| `lifestyle` | `scene` | `watercolor` | — | Travel, wellness, lifestyle, creative |
|
| 45 |
+
| `history` | `timeline` | `elegant` | — | Historical overviews, milestones |
|
| 46 |
+
| `evolution` | `timeline` | `warm` | — | Progress narratives, growth journeys |
|
| 47 |
+
|
| 48 |
+
### Editorial & Opinion
|
| 49 |
+
|
| 50 |
+
| Preset | Type | Style | Palette | Best For |
|
| 51 |
+
|----------|------|-------|---------|----------|
|
| 52 |
+
| `opinion-piece` | `scene` | `screen-print` | — | Op-eds, commentary, critical essays |
|
| 53 |
+
| `editorial-poster` | `comparison` | `screen-print` | — | Debate, contrasting viewpoints |
|
| 54 |
+
| `cinematic` | `scene` | `screen-print` | — | Dramatic narratives, cultural essays |
|
| 55 |
+
|
| 56 |
+
## Content Type → Preset Recommendations
|
| 57 |
+
|
| 58 |
+
Use this table during Step 3 to recommend presets based on Step 2 content analysis:
|
| 59 |
+
|
| 60 |
+
| Content Type (Step 2) | Primary Preset | Alternatives |
|
| 61 |
+
|------------------------|----------------|--------------|
|
| 62 |
+
| Technical | `tech-explainer` | `system-design`, `architecture` |
|
| 63 |
+
| Tutorial | `tutorial` | `process-flow`, `knowledge-base`, `edu-visual` |
|
| 64 |
+
| Methodology / Framework | `system-design` | `architecture`, `process-flow` |
|
| 65 |
+
| Data / Metrics | `data-report` | `versus`, `tech-explainer` |
|
| 66 |
+
| Comparison / Review | `versus` | `business-compare`, `editorial-poster`, `ink-notes-compare` |
|
| 67 |
+
| Manifesto / Mindset shift / Professional visual note | `ink-notes-compare` | `ink-notes-framework`, `ink-notes-flow` |
|
| 68 |
+
| Narrative / Personal | `storytelling` | `lifestyle`, `evolution` |
|
| 69 |
+
| Opinion / Editorial | `opinion-piece` | `cinematic`, `editorial-poster` |
|
| 70 |
+
| Historical / Timeline | `history` | `evolution` |
|
| 71 |
+
| Academic / Research | `science-paper` | `tech-explainer`, `data-report` |
|
| 72 |
+
| SaaS / Product | `saas-guide` | `knowledge-base`, `process-flow`, `warm-knowledge` |
|
| 73 |
+
| Education / Knowledge | `edu-visual` | `knowledge-base`, `tutorial`, `hand-drawn-edu` |
|
| 74 |
+
|
| 75 |
+
## Override Examples
|
| 76 |
+
|
| 77 |
+
- "use the tech-explainer preset but swap the style for notion" = infographic type with notion style
|
| 78 |
+
- "storytelling preset with timeline type" = timeline type with warm style
|
| 79 |
+
|
| 80 |
+
Explicit type/style/palette mentions in the user's request always override preset values.
|
optional-skills/creative/baoyu-article-illustrator/references/styles.md
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Style Reference
|
| 2 |
+
|
| 3 |
+
## Core Styles
|
| 4 |
+
|
| 5 |
+
Simplified style tier for quick selection:
|
| 6 |
+
|
| 7 |
+
| Core Style | Maps To | Best For |
|
| 8 |
+
|------------|---------|----------|
|
| 9 |
+
| `vector` | vector-illustration | Knowledge articles, tutorials, tech content |
|
| 10 |
+
| `minimal-flat` | notion | General, knowledge sharing, SaaS |
|
| 11 |
+
| `sci-fi` | blueprint | AI, frontier tech, system design |
|
| 12 |
+
| `hand-drawn` | sketch/warm | Relaxed, reflective, casual content |
|
| 13 |
+
| `editorial` | editorial | Processes, data, journalism |
|
| 14 |
+
| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
|
| 15 |
+
| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
|
| 16 |
+
|
| 17 |
+
Use Core Styles for most cases. See full Style Gallery below for granular control.
|
| 18 |
+
|
| 19 |
+
---
|
| 20 |
+
|
| 21 |
+
## Style Gallery
|
| 22 |
+
|
| 23 |
+
| Style | Description | Best For |
|
| 24 |
+
|-------|-------------|----------|
|
| 25 |
+
| `vector-illustration` | Clean flat vector art with bold shapes | Knowledge articles, tutorials, tech content |
|
| 26 |
+
| `notion` | Minimalist hand-drawn line art | Knowledge sharing, SaaS, productivity |
|
| 27 |
+
| `elegant` | Refined, sophisticated | Business, thought leadership |
|
| 28 |
+
| `warm` | Friendly, approachable | Personal growth, lifestyle, education |
|
| 29 |
+
| `minimal` | Ultra-clean, zen-like | Philosophy, minimalism, core concepts |
|
| 30 |
+
| `blueprint` | Technical schematics | Architecture, system design, engineering |
|
| 31 |
+
| `watercolor` | Soft artistic with natural warmth | Lifestyle, travel, creative |
|
| 32 |
+
| `editorial` | Magazine-style infographic | Tech explainers, journalism |
|
| 33 |
+
| `scientific` | Academic precise diagrams | Biology, chemistry, technical research |
|
| 34 |
+
| `chalkboard` | Classroom chalk drawing style | Education, teaching, explanations |
|
| 35 |
+
| `fantasy-animation` | Ghibli/Disney-inspired hand-drawn | Storybook, magical, emotional |
|
| 36 |
+
| `flat` | Modern bold geometric shapes | Modern digital, contemporary |
|
| 37 |
+
| `flat-doodle` | Cute flat with bold outlines | Cute, friendly, approachable |
|
| 38 |
+
| `intuition-machine` | Technical briefing with aged paper | Technical briefings, academic |
|
| 39 |
+
| `nature` | Organic earthy illustration | Environmental, wellness |
|
| 40 |
+
| `pixel-art` | Retro 8-bit gaming aesthetic | Gaming, retro tech |
|
| 41 |
+
| `playful` | Whimsical pastel doodles | Fun, casual, educational |
|
| 42 |
+
| `retro` | 80s/90s neon geometric | 80s/90s nostalgic, bold |
|
| 43 |
+
| `sketch` | Raw pencil notebook style | Brainstorming, creative exploration |
|
| 44 |
+
| `screen-print` | Bold poster art, halftone textures, limited colors | Opinion, editorial, cultural, cinematic |
|
| 45 |
+
| `sketch-notes` | Soft hand-drawn warm notes | Educational, warm notes |
|
| 46 |
+
| `ink-notes` | Black ink on pure white, sparse semantic accents, hand-lettered (à la Mike Rohde's sketchnoting) | Before/After essays, tech manifestos, framework analogies |
|
| 47 |
+
| `vintage` | Aged parchment historical | Historical, heritage |
|
| 48 |
+
|
| 49 |
+
Full specifications: `references/styles/<style>.md`
|
| 50 |
+
|
| 51 |
+
## Type × Style Compatibility Matrix
|
| 52 |
+
|
| 53 |
+
| | vector-illustration | notion | warm | minimal | blueprint | watercolor | elegant | editorial | scientific | screen-print |
|
| 54 |
+
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
| 55 |
+
| infographic | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ |
|
| 56 |
+
| scene | ✓ | ✓ | ✓✓ | ✓ | ✗ | ✓✓ | ✓ | ✓ | ✗ | ✓✓ |
|
| 57 |
+
| flowchart | ✓✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✗ | ✓ | ✓✓ | ✓ | ✗ |
|
| 58 |
+
| comparison | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓ |
|
| 59 |
+
| framework | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✗ | ✓✓ | ✓ | ✓✓ | ✓ |
|
| 60 |
+
| timeline | ✓ | ✓✓ | ✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ | ✓ |
|
| 61 |
+
|
| 62 |
+
✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended
|
| 63 |
+
|
| 64 |
+
## Auto Selection by Type
|
| 65 |
+
|
| 66 |
+
| Type | Primary Style | Secondary Styles |
|
| 67 |
+
|------|---------------|------------------|
|
| 68 |
+
| infographic | vector-illustration | notion, blueprint, editorial |
|
| 69 |
+
| scene | warm | watercolor, elegant |
|
| 70 |
+
| flowchart | vector-illustration | notion, blueprint |
|
| 71 |
+
| comparison | vector-illustration | notion, elegant |
|
| 72 |
+
| framework | blueprint | vector-illustration, notion |
|
| 73 |
+
| timeline | elegant | warm, editorial |
|
| 74 |
+
|
| 75 |
+
## Auto Selection by Content Signals
|
| 76 |
+
|
| 77 |
+
| Content Signals | Recommended Type | Recommended Style |
|
| 78 |
+
|-----------------|------------------|-------------------|
|
| 79 |
+
| API, metrics, data, comparison, numbers | infographic | blueprint, vector-illustration |
|
| 80 |
+
| Knowledge, concept, tutorial, learning, guide | infographic | vector-illustration, notion |
|
| 81 |
+
| Tech, AI, programming, development, code | infographic | vector-illustration, blueprint |
|
| 82 |
+
| How-to, steps, workflow, process, tutorial | flowchart | vector-illustration, notion |
|
| 83 |
+
| Framework, model, architecture, principles | framework | blueprint, vector-illustration |
|
| 84 |
+
| vs, pros/cons, before/after, alternatives | comparison | vector-illustration, notion |
|
| 85 |
+
| Manifesto, mindset shift, workforce, OS, whiteboard, professional visual note | comparison / framework | ink-notes |
|
| 86 |
+
| Story, emotion, journey, experience, personal | scene | warm, watercolor |
|
| 87 |
+
| History, timeline, progress, evolution | timeline | elegant, warm |
|
| 88 |
+
| Productivity, SaaS, tool, app, software | infographic | notion, vector-illustration |
|
| 89 |
+
| Business, professional, strategy, corporate | framework | elegant |
|
| 90 |
+
| Opinion, editorial, culture, philosophy, cinematic, dramatic, poster | scene | screen-print |
|
| 91 |
+
| Biology, chemistry, medical, scientific | infographic | scientific |
|
| 92 |
+
| Explainer, journalism, magazine, investigation | infographic | editorial |
|
| 93 |
+
|
| 94 |
+
## Style Characteristics by Type
|
| 95 |
+
|
| 96 |
+
### infographic + vector-illustration
|
| 97 |
+
- Clean flat vector shapes, bold geometric forms
|
| 98 |
+
- Vibrant but harmonious color palette
|
| 99 |
+
- Clear visual hierarchy with icons and labels
|
| 100 |
+
- Modern, professional, highly readable
|
| 101 |
+
- Perfect for knowledge articles and tutorials
|
| 102 |
+
|
| 103 |
+
### flowchart + vector-illustration
|
| 104 |
+
- Bold arrows and connectors
|
| 105 |
+
- Distinct step containers with icons
|
| 106 |
+
- Clean progression flow
|
| 107 |
+
- High contrast for readability
|
| 108 |
+
|
| 109 |
+
### comparison + vector-illustration
|
| 110 |
+
- Split layout with clear visual separation
|
| 111 |
+
- Bold iconography for each side
|
| 112 |
+
- Color-coded distinctions
|
| 113 |
+
- Easy at-a-glance comparison
|
| 114 |
+
|
| 115 |
+
### framework + vector-illustration
|
| 116 |
+
- Geometric node representations
|
| 117 |
+
- Clear hierarchical structure
|
| 118 |
+
- Bold connecting lines
|
| 119 |
+
- Modern system diagram aesthetic
|
| 120 |
+
|
| 121 |
+
### infographic + blueprint
|
| 122 |
+
- Technical precision, schematic lines
|
| 123 |
+
- Grid-based layout, clear zones
|
| 124 |
+
- Monospace labels, data-focused
|
| 125 |
+
- Blue/white color scheme
|
| 126 |
+
|
| 127 |
+
### infographic + notion
|
| 128 |
+
- Hand-drawn feel, approachable
|
| 129 |
+
- Soft icons, rounded elements
|
| 130 |
+
- Neutral palette, clean backgrounds
|
| 131 |
+
- Perfect for SaaS/productivity
|
| 132 |
+
|
| 133 |
+
### scene + warm
|
| 134 |
+
- Golden hour lighting, cozy atmosphere
|
| 135 |
+
- Soft gradients, natural textures
|
| 136 |
+
- Inviting, personal feeling
|
| 137 |
+
- Great for storytelling
|
| 138 |
+
|
| 139 |
+
### scene + watercolor
|
| 140 |
+
- Artistic, painterly effect
|
| 141 |
+
- Soft edges, color bleeding
|
| 142 |
+
- Dreamy, creative mood
|
| 143 |
+
- Best for lifestyle/travel
|
| 144 |
+
|
| 145 |
+
### flowchart + notion
|
| 146 |
+
- Clear step indicators
|
| 147 |
+
- Simple arrow connections
|
| 148 |
+
- Minimal decoration
|
| 149 |
+
- Focus on process clarity
|
| 150 |
+
|
| 151 |
+
### flowchart + blueprint
|
| 152 |
+
- Technical precision
|
| 153 |
+
- Detailed connection points
|
| 154 |
+
- Engineering aesthetic
|
| 155 |
+
- For complex systems
|
| 156 |
+
|
| 157 |
+
### comparison + elegant
|
| 158 |
+
- Refined dividers
|
| 159 |
+
- Balanced typography
|
| 160 |
+
- Professional appearance
|
| 161 |
+
- Business comparisons
|
| 162 |
+
|
| 163 |
+
### framework + blueprint
|
| 164 |
+
- Precise node connections
|
| 165 |
+
- Hierarchical clarity
|
| 166 |
+
- System architecture feel
|
| 167 |
+
- Technical frameworks
|
| 168 |
+
|
| 169 |
+
### timeline + elegant
|
| 170 |
+
- Sophisticated markers
|
| 171 |
+
- Refined typography
|
| 172 |
+
- Historical gravitas
|
| 173 |
+
- Professional presentations
|
| 174 |
+
|
| 175 |
+
### timeline + warm
|
| 176 |
+
- Friendly progression
|
| 177 |
+
- Organic flow
|
| 178 |
+
- Personal journey feel
|
| 179 |
+
- Growth narratives
|
| 180 |
+
|
| 181 |
+
### scene + screen-print
|
| 182 |
+
- Bold silhouettes, symbolic compositions
|
| 183 |
+
- 2-5 flat colors with halftone textures
|
| 184 |
+
- Figure-ground inversion (negative space tells secondary story)
|
| 185 |
+
- Vintage poster aesthetic, conceptual not literal
|
| 186 |
+
- Great for opinion pieces and cultural commentary
|
| 187 |
+
|
| 188 |
+
### comparison + screen-print
|
| 189 |
+
- Split duotone composition (one color per side)
|
| 190 |
+
- Bold geometric dividers
|
| 191 |
+
- Symbolic icons over detailed rendering
|
| 192 |
+
- High contrast, immediate visual impact
|
| 193 |
+
|
| 194 |
+
### framework + screen-print
|
| 195 |
+
- Geometric node representations with stencil-cut edges
|
| 196 |
+
- Limited color coding (one color per concept level)
|
| 197 |
+
- Clean silhouette-based iconography
|
| 198 |
+
- Poster-style hierarchy with bold typography
|
| 199 |
+
|
| 200 |
+
---
|
| 201 |
+
|
| 202 |
+
## Palette Gallery
|
| 203 |
+
|
| 204 |
+
Palettes override a style's default colors. Combine any style with any palette (e.g. `style=vector-illustration, palette=macaron`).
|
| 205 |
+
|
| 206 |
+
| Palette | Description | Best For |
|
| 207 |
+
|---------|-------------|----------|
|
| 208 |
+
| `macaron` | Soft pastel blocks (blue, mint, lavender, peach) on warm cream | Educational, knowledge, tutorials |
|
| 209 |
+
| `warm` | Warm earth tones (orange, terracotta, gold) on soft peach, no cool colors | Brand, product, lifestyle |
|
| 210 |
+
| `neon` | Vibrant neon (pink, cyan, yellow) on dark purple | Gaming, retro, pop culture |
|
| 211 |
+
| `mono-ink` | Black ink on pure white with sparse semantic accents (coral red, muted teal, dusty lavender) | Professional visual notes, Before/After, manifestos |
|
| 212 |
+
|
| 213 |
+
Full specifications: `references/palettes/<palette>.md`
|
| 214 |
+
|
| 215 |
+
When no palette is specified, the style's built-in Color Palette is used.
|
| 216 |
+
|
| 217 |
+
## Palette Override Rules
|
| 218 |
+
|
| 219 |
+
1. Read style file → rendering rules (Visual Elements, Style Rules)
|
| 220 |
+
2. Read palette file → Colors + Background
|
| 221 |
+
3. Palette colors **replace** style's default Color Palette
|
| 222 |
+
4. Palette Background **replaces** style's default Background color
|
| 223 |
+
5. Style's texture description is preserved
|
| 224 |
+
|
optional-skills/creative/baoyu-article-illustrator/references/styles/blueprint.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# blueprint
|
| 2 |
+
|
| 3 |
+
Precise technical blueprint style with engineering precision
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Clean, structured visual metaphors using blueprints, diagrams, and schematics. Precise, analytical and aesthetically refined. Information presented in grid-based layouts with engineering precision. Technical drawing quality with professional polish.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Blueprint Off-White (#FAF8F5)
|
| 12 |
+
- Texture: Subtle grid overlay, engineering paper feel
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Blueprint Paper | #FAF8F5 | Primary background |
|
| 19 |
+
| Grid | Light Gray | #E5E5E5 | Background grid lines |
|
| 20 |
+
| Primary Text | Deep Slate | #334155 | Headlines, body |
|
| 21 |
+
| Primary Accent | Engineering Blue | #2563EB | Key elements |
|
| 22 |
+
| Secondary Accent | Navy Blue | #1E3A5F | Supporting elements |
|
| 23 |
+
| Tertiary | Light Blue | #BFDBFE | Fills, backgrounds |
|
| 24 |
+
| Warning | Amber | #F59E0B | Warnings, emphasis |
|
| 25 |
+
|
| 26 |
+
## Visual Elements
|
| 27 |
+
|
| 28 |
+
- Precise lines with consistent stroke weights
|
| 29 |
+
- Technical schematics and clean vector graphics
|
| 30 |
+
- Thin line work in technical drawing style
|
| 31 |
+
- Connection lines: straight or 90-degree angles only
|
| 32 |
+
- Data visualization with minimal charts
|
| 33 |
+
- Dimension lines and measurement indicators
|
| 34 |
+
- Cross-section style diagrams
|
| 35 |
+
- Isometric or orthographic projections
|
| 36 |
+
|
| 37 |
+
## Style Rules
|
| 38 |
+
|
| 39 |
+
### Do
|
| 40 |
+
|
| 41 |
+
- Maintain consistent line weights
|
| 42 |
+
- Use grid alignment for all elements
|
| 43 |
+
- Keep color palette restrained
|
| 44 |
+
- Create clear visual hierarchy through scale
|
| 45 |
+
- Use geometric precision for all shapes
|
| 46 |
+
|
| 47 |
+
### Don't
|
| 48 |
+
|
| 49 |
+
- Use hand-drawn or organic shapes
|
| 50 |
+
- Add decorative flourishes
|
| 51 |
+
- Use curved connection lines
|
| 52 |
+
- Include photographic elements
|
| 53 |
+
- Add unnecessary embellishments
|
| 54 |
+
|
| 55 |
+
## Best For
|
| 56 |
+
|
| 57 |
+
Technical architecture, system design, data analysis, engineering documentation, process flows, infrastructure articles
|
optional-skills/creative/baoyu-article-illustrator/references/styles/chalkboard.md
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# chalkboard
|
| 2 |
+
|
| 3 |
+
Black chalkboard background with colorful chalk drawing style
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Classic classroom chalkboard aesthetic with hand-drawn chalk illustrations. Nostalgic educational feel with imperfect, sketchy lines that capture the warmth of traditional teaching. Colorful chalk creates visual hierarchy while maintaining the authentic chalkboard experience.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Chalkboard Black (#1A1A1A) or Dark Green-Black (#1C2B1C)
|
| 12 |
+
- Texture: Realistic chalkboard texture with subtle scratches, dust particles, and faint eraser marks
|
| 13 |
+
|
| 14 |
+
## Typography
|
| 15 |
+
|
| 16 |
+
Hand-drawn chalk lettering style with visible chalk texture. Imperfect baseline adds authenticity. White or bright colored chalk for emphasis.
|
| 17 |
+
|
| 18 |
+
## Color Palette
|
| 19 |
+
|
| 20 |
+
| Role | Color | Hex | Usage |
|
| 21 |
+
|------|-------|-----|-------|
|
| 22 |
+
| Background | Chalkboard Black | #1A1A1A | Primary background |
|
| 23 |
+
| Alt Background | Green-Black | #1C2B1C | Traditional green board |
|
| 24 |
+
| Primary Text | Chalk White | #F5F5F5 | Main text, outlines |
|
| 25 |
+
| Accent 1 | Chalk Yellow | #FFE566 | Highlights, emphasis |
|
| 26 |
+
| Accent 2 | Chalk Pink | #FF9999 | Secondary highlights |
|
| 27 |
+
| Accent 3 | Chalk Blue | #66B3FF | Diagrams, links |
|
| 28 |
+
| Accent 4 | Chalk Green | #90EE90 | Success, nature |
|
| 29 |
+
| Accent 5 | Chalk Orange | #FFB366 | Warnings, energy |
|
| 30 |
+
|
| 31 |
+
## Visual Elements
|
| 32 |
+
|
| 33 |
+
- Hand-drawn chalk illustrations with sketchy, imperfect lines
|
| 34 |
+
- Chalk dust effects around text and key elements
|
| 35 |
+
- Doodles: stars, arrows, underlines, circles, checkmarks
|
| 36 |
+
- Mathematical formulas and simple diagrams
|
| 37 |
+
- Eraser smudges and chalk residue textures
|
| 38 |
+
- Wooden frame border optional
|
| 39 |
+
- Stick figures and simple icons
|
| 40 |
+
- Connection lines with hand-drawn feel
|
| 41 |
+
|
| 42 |
+
## Style Rules
|
| 43 |
+
|
| 44 |
+
### Do
|
| 45 |
+
|
| 46 |
+
- Maintain authentic chalk texture on all elements
|
| 47 |
+
- Use imperfect, hand-drawn quality throughout
|
| 48 |
+
- Add subtle chalk dust and smudge effects
|
| 49 |
+
- Create visual hierarchy with color variety
|
| 50 |
+
- Include playful doodles and annotations
|
| 51 |
+
|
| 52 |
+
### Don't
|
| 53 |
+
|
| 54 |
+
- Use perfect geometric shapes
|
| 55 |
+
- Create clean digital-looking lines
|
| 56 |
+
- Add photorealistic elements
|
| 57 |
+
- Use gradients or glossy effects
|
| 58 |
+
- Make it look computerized
|
| 59 |
+
|
| 60 |
+
## Best For
|
| 61 |
+
|
| 62 |
+
Educational articles, tutorials, teaching content, workshops, informal learning, knowledge sharing, how-to guides, classroom-style explanations
|
optional-skills/creative/baoyu-article-illustrator/references/styles/editorial.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# editorial
|
| 2 |
+
|
| 3 |
+
Magazine-style editorial infographic for professional content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
High-quality magazine explainer aesthetic. Clear visual storytelling with structured layouts and professional typography. Think Wired, The Verge, or quality science publications. Complex information made digestible.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Pure White (#FFFFFF) or Light Gray (#F8F9FA)
|
| 12 |
+
- Texture: None or subtle paper grain
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Pure White | #FFFFFF | Primary background |
|
| 19 |
+
| Alt Background | Light Gray | #F8F9FA | Section backgrounds |
|
| 20 |
+
| Primary Text | Near Black | #1A1A1A | Headlines, body |
|
| 21 |
+
| Secondary Text | Dark Gray | #4A5568 | Captions |
|
| 22 |
+
| Accent 1 | Editorial Blue | #2563EB | Primary accent |
|
| 23 |
+
| Accent 2 | Coral | #F97316 | Secondary accent |
|
| 24 |
+
| Accent 3 | Emerald | #10B981 | Positive elements |
|
| 25 |
+
| Accent 4 | Amber | #F59E0B | Attention points |
|
| 26 |
+
| Dividers | Medium Gray | #D1D5DB | Section dividers |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Clean flat illustrations
|
| 31 |
+
- Structured multi-section layouts
|
| 32 |
+
- Callout boxes for insights
|
| 33 |
+
- Icon-based visualizations
|
| 34 |
+
- Visual metaphors for concepts
|
| 35 |
+
- Flow diagrams with hierarchy
|
| 36 |
+
- Pull quotes and highlights
|
| 37 |
+
- Clear section dividers
|
| 38 |
+
|
| 39 |
+
## Style Rules
|
| 40 |
+
|
| 41 |
+
### Do
|
| 42 |
+
|
| 43 |
+
- Create clear narrative flow
|
| 44 |
+
- Use structured layouts
|
| 45 |
+
- Include callout boxes
|
| 46 |
+
- Design visual metaphors
|
| 47 |
+
- Maintain magazine polish
|
| 48 |
+
|
| 49 |
+
### Don't
|
| 50 |
+
|
| 51 |
+
- Use photographic imagery
|
| 52 |
+
- Create cluttered layouts
|
| 53 |
+
- Mix too many styles
|
| 54 |
+
- Add purposeless decoration
|
| 55 |
+
- Compromise clarity for style
|
| 56 |
+
|
| 57 |
+
## Best For
|
| 58 |
+
|
| 59 |
+
Technology explainers, science communication, research articles, policy analysis, investigative pieces, thought leadership, long-form journalism
|
optional-skills/creative/baoyu-article-illustrator/references/styles/elegant.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# elegant
|
| 2 |
+
|
| 3 |
+
Refined, sophisticated illustration style for professional content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Elegant and refined visual approach with sophisticated color palette. Professional polish with subtle artistic touches. Emphasizes clarity and thoughtful composition. Conveys authority and trustworthiness without being cold or clinical.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Warm Cream (#F5F0E6) or Soft Beige (#FAF6F0)
|
| 12 |
+
- Texture: Subtle paper texture, very light grain
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Warm Cream | #F5F0E6 | Primary background |
|
| 19 |
+
| Primary | Soft Coral | #E8A598 | Main accent color |
|
| 20 |
+
| Secondary | Muted Teal | #5B8A8A | Supporting elements |
|
| 21 |
+
| Tertiary | Dusty Rose | #D4A5A5 | Subtle highlights |
|
| 22 |
+
| Accent | Gold | #C9A962 | Premium touches |
|
| 23 |
+
| Alt Accent | Copper | #B87333 | Warm metallic notes |
|
| 24 |
+
| Text | Charcoal | #3D3D3D | Text and outlines |
|
| 25 |
+
|
| 26 |
+
## Visual Elements
|
| 27 |
+
|
| 28 |
+
- Delicate line work with refined strokes
|
| 29 |
+
- Subtle icons with balanced weight
|
| 30 |
+
- Graceful curves and flowing compositions
|
| 31 |
+
- Soft gradients with smooth transitions
|
| 32 |
+
- Balanced whitespace and breathing room
|
| 33 |
+
- Thin borders and elegant dividers
|
| 34 |
+
- Subtle drop shadows for depth
|
| 35 |
+
|
| 36 |
+
## Style Rules
|
| 37 |
+
|
| 38 |
+
### Do
|
| 39 |
+
|
| 40 |
+
- Use refined color combinations
|
| 41 |
+
- Create balanced, harmonious compositions
|
| 42 |
+
- Keep elements light and airy
|
| 43 |
+
- Use subtle gradients sparingly
|
| 44 |
+
- Maintain generous margins
|
| 45 |
+
|
| 46 |
+
### Don't
|
| 47 |
+
|
| 48 |
+
- Use harsh contrasts
|
| 49 |
+
- Overcrowd the composition
|
| 50 |
+
- Add playful or casual elements
|
| 51 |
+
- Use neon or overly bright colors
|
| 52 |
+
- Create busy or cluttered layouts
|
| 53 |
+
|
| 54 |
+
## Best For
|
| 55 |
+
|
| 56 |
+
Professional articles, thought leadership pieces, business topics, executive communications, corporate blogs, strategy discussions, industry analysis
|
optional-skills/creative/baoyu-article-illustrator/references/styles/fantasy-animation.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# fantasy-animation
|
| 2 |
+
|
| 3 |
+
Whimsical hand-drawn animation style inspired by Ghibli/Disney
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Charming hand-drawn animation aesthetic reminiscent of classic Disney, Studio Ghibli, or European storybook illustration. Soft, painterly textures with warm, inviting colors. Friendly characters, magical elements, and storybook feel. Enchanting, nostalgic, and emotionally engaging.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Soft Sky Blue (#E8F4FC) or Warm Cream (#FFF8E7)
|
| 12 |
+
- Texture: Subtle watercolor wash, soft brush strokes
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Soft Sky Blue | #E8F4FC | Primary background |
|
| 19 |
+
| Alt Background | Warm Cream | #FFF8E7 | Secondary areas |
|
| 20 |
+
| Primary Text | Deep Forest | #2D5A3D | Headlines |
|
| 21 |
+
| Body Text | Warm Brown | #5D4E37 | Content |
|
| 22 |
+
| Accent 1 | Golden Yellow | #F4D03F | Magic, highlights |
|
| 23 |
+
| Accent 2 | Rose Pink | #E8A0BF | Warmth, charm |
|
| 24 |
+
| Accent 3 | Sage Green | #87A96B | Nature elements |
|
| 25 |
+
| Accent 4 | Sky Blue | #7EC8E3 | Air, water, dreams |
|
| 26 |
+
| Accent 5 | Coral | #F08080 | Emphasis, life |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Central illustrated character (friendly, expressive)
|
| 31 |
+
- Small companion creatures (animals, magical beings)
|
| 32 |
+
- Storybook-style environment backgrounds
|
| 33 |
+
- Magical floating objects (books, orbs, sparkles)
|
| 34 |
+
- Decorative elements: stars, flowers, leaves
|
| 35 |
+
- Soft shadows and gentle highlights
|
| 36 |
+
- Layered depth with foreground/background
|
| 37 |
+
|
| 38 |
+
## Style Rules
|
| 39 |
+
|
| 40 |
+
### Do
|
| 41 |
+
|
| 42 |
+
- Create warm, inviting compositions
|
| 43 |
+
- Use soft edges and painterly textures
|
| 44 |
+
- Include charming character illustrations
|
| 45 |
+
- Add magical decorative touches
|
| 46 |
+
- Maintain storybook narrative feel
|
| 47 |
+
|
| 48 |
+
### Don't
|
| 49 |
+
|
| 50 |
+
- Use harsh geometric shapes
|
| 51 |
+
- Create dark or intimidating imagery
|
| 52 |
+
- Add photorealistic elements
|
| 53 |
+
- Use cold color palettes
|
| 54 |
+
- Make it look digital/computerized
|
| 55 |
+
|
| 56 |
+
## Best For
|
| 57 |
+
|
| 58 |
+
Educational content, children's articles, storytelling, creative topics, fantasy/gaming, inspirational pieces, family-friendly content
|
optional-skills/creative/baoyu-article-illustrator/references/styles/flat-doodle.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# flat-doodle
|
| 2 |
+
|
| 3 |
+
Cute flat doodle illustration style with bold outlines
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Cheerful and approachable visual style combining flat design with doodle charm. Features bold black outlines around simple shapes. Bright pastel colors with no gradients or shading. Cute rounded proportions that feel friendly. Clean white backgrounds create focus and clarity.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Clean White (#FFFFFF)
|
| 12 |
+
- Texture: None - pure white isolated background
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | White | #FFFFFF | Primary background |
|
| 19 |
+
| Primary | Pastel Pink | #FFB6C1 | Main elements |
|
| 20 |
+
| Secondary | Mint | #98D8C8 | Supporting elements |
|
| 21 |
+
| Tertiary | Lavender | #C8A2C8 | Accent elements |
|
| 22 |
+
| Accent 1 | Butter Yellow | #FFFACD | Highlight pop |
|
| 23 |
+
| Accent 2 | Sky Blue | #87CEEB | Cool accent |
|
| 24 |
+
| Accent 3 | Soft Coral | #F88379 | Warm accent |
|
| 25 |
+
| Outline | Bold Black | #000000 | All outlines |
|
| 26 |
+
| Text | Black | #1A1A1A | Text elements |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Bold black outlines around all shapes
|
| 31 |
+
- Simple flat color fills
|
| 32 |
+
- Cute rounded proportions
|
| 33 |
+
- Minimal geometric shapes
|
| 34 |
+
- Productivity icons (laptops, calendars, checkmarks)
|
| 35 |
+
- Isolated elements on white
|
| 36 |
+
- No shading or gradients
|
| 37 |
+
- Hand-drawn quality with clean edges
|
| 38 |
+
|
| 39 |
+
## Style Rules
|
| 40 |
+
|
| 41 |
+
### Do
|
| 42 |
+
|
| 43 |
+
- Use bold black outlines consistently
|
| 44 |
+
- Keep shapes simple and rounded
|
| 45 |
+
- Use bright pastel palette
|
| 46 |
+
- Isolate elements on white background
|
| 47 |
+
- Maintain cute proportions
|
| 48 |
+
- Keep minimal shading
|
| 49 |
+
|
| 50 |
+
### Don't
|
| 51 |
+
|
| 52 |
+
- Add shadows or depth effects
|
| 53 |
+
- Use gradients or textures
|
| 54 |
+
- Create complex detailed illustrations
|
| 55 |
+
- Overlap too many elements
|
| 56 |
+
- Use dark or moody backgrounds
|
| 57 |
+
- Add realistic proportions
|
| 58 |
+
|
| 59 |
+
## Best For
|
| 60 |
+
|
| 61 |
+
Productivity articles, SaaS and app content, workflow tutorials, beginner guides, casual business content, tool introductions, lifestyle productivity
|
optional-skills/creative/baoyu-article-illustrator/references/styles/flat.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# flat
|
| 2 |
+
|
| 3 |
+
Modern flat vector illustration style for contemporary content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Contemporary flat design aesthetic with bold shapes and limited depth. Clean geometric forms with no gradients or shadows. Modern, accessible, and highly readable. Optimized for digital consumption with scalable vector quality.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: White (#FFFFFF) or Soft Gray (#F5F5F5)
|
| 12 |
+
- Texture: None - clean solid backgrounds
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | White | #FFFFFF | Primary background |
|
| 19 |
+
| Alt Background | Soft Gray | #F5F5F5 | Accent areas |
|
| 20 |
+
| Primary | Vibrant Blue | #3B82F6 | Main elements |
|
| 21 |
+
| Secondary | Coral | #F97316 | Supporting elements |
|
| 22 |
+
| Tertiary | Emerald | #10B981 | Accent elements |
|
| 23 |
+
| Accent 1 | Purple | #8B5CF6 | Additional accent |
|
| 24 |
+
| Accent 2 | Amber | #F59E0B | Highlight |
|
| 25 |
+
| Text | Dark Slate | #1E293B | Text elements |
|
| 26 |
+
| Light | Light Gray | #E5E7EB | Subtle elements |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Bold geometric shapes
|
| 31 |
+
- Flat color fills with no gradients
|
| 32 |
+
- Simple character illustrations
|
| 33 |
+
- Clean icon designs
|
| 34 |
+
- Minimal line work
|
| 35 |
+
- Overlapping shape compositions
|
| 36 |
+
- Abstract concept visualizations
|
| 37 |
+
- Consistent stroke weights
|
| 38 |
+
|
| 39 |
+
## Style Rules
|
| 40 |
+
|
| 41 |
+
### Do
|
| 42 |
+
|
| 43 |
+
- Use flat solid colors
|
| 44 |
+
- Create clean geometric shapes
|
| 45 |
+
- Keep elements simple
|
| 46 |
+
- Maintain consistent styling
|
| 47 |
+
- Use bold color combinations
|
| 48 |
+
|
| 49 |
+
### Don't
|
| 50 |
+
|
| 51 |
+
- Add shadows or depth
|
| 52 |
+
- Use gradients or textures
|
| 53 |
+
- Create realistic illustrations
|
| 54 |
+
- Add unnecessary details
|
| 55 |
+
- Use photographic elements
|
| 56 |
+
|
| 57 |
+
## Best For
|
| 58 |
+
|
| 59 |
+
Modern articles, app and product content, startup stories, digital topics, contemporary business, tech company blogs, social media content
|
optional-skills/creative/baoyu-article-illustrator/references/styles/ink-notes.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ink-notes
|
| 2 |
+
|
| 3 |
+
Professional black-ink visual notes on pure white, in the tradition of Mike Rohde's sketchnoting
|
| 4 |
+
|
| 5 |
+
## Compared to sketch-notes
|
| 6 |
+
|
| 7 |
+
`ink-notes` and `sketch-notes` are distinct styles. Pick the right one:
|
| 8 |
+
|
| 9 |
+
| | `sketch-notes` | `ink-notes` |
|
| 10 |
+
|---|---|---|
|
| 11 |
+
| Background | Warm Off-White #FAF8F0 with paper grain | Pure White #FFFFFF, clean, no texture |
|
| 12 |
+
| Palette | Soft warm accents (orange, mustard, sage, light blue) | Black ink dominant + sparse semantic accents |
|
| 13 |
+
| Feel | Soft, warm, educational, approachable | Professional, structured, whiteboard-presentation |
|
| 14 |
+
| Best For | Friendly tutorials, onboarding, casual explainers | Before/After essays, tech manifestos, framework analogies |
|
| 15 |
+
|
| 16 |
+
When in doubt: warm & friendly → `sketch-notes`. Disciplined & professional → `ink-notes`.
|
| 17 |
+
|
| 18 |
+
## Design Aesthetic
|
| 19 |
+
|
| 20 |
+
Disciplined hand-drawn visual note. Confident black ink line work with slight wobble, hand-lettered typography, and sparse color accents used only for semantic emphasis. Feels like a skilled visual notetaker's whiteboard presentation — clean, structured, intentionally hand-drawn rather than decorative.
|
| 21 |
+
|
| 22 |
+
## Background
|
| 23 |
+
|
| 24 |
+
- Color: Pure White (#FFFFFF)
|
| 25 |
+
- Texture: Clean, no grain, no tint
|
| 26 |
+
|
| 27 |
+
## Color Palette
|
| 28 |
+
|
| 29 |
+
| Role | Color | Hex | Usage |
|
| 30 |
+
|------|-------|-----|-------|
|
| 31 |
+
| Background | Pure White | #FFFFFF | Canvas |
|
| 32 |
+
| Primary Ink | Near Black | #1A1A1A | All lines, text, figures, arrows |
|
| 33 |
+
| Accent Warm | Coral Red | #E8655A | Risk, problem, gap, emphasis |
|
| 34 |
+
| Accent Cool | Muted Teal | #5FA8A8 | Positive, solution, "after" state |
|
| 35 |
+
| Accent Neutral | Dusty Lavender | #9B8AB5 | Neutral tags, category labels |
|
| 36 |
+
| Soft Fill | Pale Gray | #F0F0F0 | Subtle zone backgrounds (optional) |
|
| 37 |
+
|
| 38 |
+
Color accents must remain under 10% of canvas area and only carry semantic meaning. Black ink does the structural work.
|
| 39 |
+
|
| 40 |
+
## Visual Elements
|
| 41 |
+
|
| 42 |
+
- Black ink line work with intentional slight wobble on all strokes
|
| 43 |
+
- Hand-lettered titles (bold, oversized) and handwritten body annotations
|
| 44 |
+
- Simple stick-figure characters with expressive poses (pointing, thinking, walking)
|
| 45 |
+
- Role labels above characters (e.g., "Tech Lead", "Compliance Officer")
|
| 46 |
+
- Thought bubbles and speech bubbles with hand-drawn outlines
|
| 47 |
+
- Rounded-rectangle frames for content groupings
|
| 48 |
+
- Dashed-border rectangles for placeholder, "coming next", or empty states
|
| 49 |
+
- Curvy hand-drawn arrows with small inline labels
|
| 50 |
+
- Vertical or horizontal dividers between comparison zones ("Before" | "After")
|
| 51 |
+
- "Mindset shift" curved arrow bridging two zones
|
| 52 |
+
- Bottom tagline: single-line hand-lettered conclusion that points the takeaway
|
| 53 |
+
- Stars, asterisks, underlines for emphasis — used sparingly
|
| 54 |
+
|
| 55 |
+
## Style Rules
|
| 56 |
+
|
| 57 |
+
### Do
|
| 58 |
+
|
| 59 |
+
- Keep background pure white with no texture or tint
|
| 60 |
+
- Let black ink dominate outlines, text, and figures
|
| 61 |
+
- Use accent colors only for semantic highlighting
|
| 62 |
+
- Keep all type hand-lettered — no computer-generated fonts
|
| 63 |
+
- Maintain confident line quality (wobble, not mess)
|
| 64 |
+
- Include a bottom tagline summarizing the main takeaway
|
| 65 |
+
- Structure content into clear zones with visible dividers
|
| 66 |
+
- Use dashed boxes for future, empty, or placeholder states
|
| 67 |
+
|
| 68 |
+
### Don't
|
| 69 |
+
|
| 70 |
+
- Use warm off-white or paper-textured backgrounds (that is sketch-notes' territory)
|
| 71 |
+
- Fill large zones with color blocks
|
| 72 |
+
- Use more than 3 accent colors per image
|
| 73 |
+
- Use perfect geometric shapes — preserve hand-drawn wobble
|
| 74 |
+
- Clutter with decorative doodles; every element must carry meaning
|
| 75 |
+
- Use gradients, shadows, or computer-generated fonts
|
| 76 |
+
|
| 77 |
+
## Type Compatibility
|
| 78 |
+
|
| 79 |
+
| Type | Rating | Notes |
|
| 80 |
+
|------|--------|-------|
|
| 81 |
+
| comparison | ✓✓ | Best fit — Before/After, Traditional vs New, side-by-side contrasts |
|
| 82 |
+
| framework | ✓✓ | OS-style command centers, layered architectures, organizational models |
|
| 83 |
+
| flowchart | ✓✓ | Process explainers with labeled stages, workforce pipelines |
|
| 84 |
+
| infographic | ✓ | Multi-zone technical summaries, manifesto-style posters |
|
| 85 |
+
| timeline | ✓ | Hand-drawn horizontal arrow with era markers and milestones |
|
| 86 |
+
| scene | ✗ | Not recommended — lacks scenic space |
|
| 87 |
+
|
| 88 |
+
## Best For
|
| 89 |
+
|
| 90 |
+
Product and engineering essays, tech manifestos, framework introductions, Before/After narratives, OS-level comparisons, workforce and organizational analogies, visual summaries of talks, thought-leadership articles
|
optional-skills/creative/baoyu-article-illustrator/references/styles/intuition-machine.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# intuition-machine
|
| 2 |
+
|
| 3 |
+
Technical briefing infographic style with aged paper and bilingual labels
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Academic/technical briefing style with clean 2D or isometric technical illustrations. Information-dense but organized with clear visual hierarchy. Vintage blueprint aesthetic with modern clarity. Multiple explanatory elements with bilingual callouts.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Aged Cream (#F5F0E6)
|
| 12 |
+
- Texture: Subtle paper texture with light creases, vintage technical print feel
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Aged Cream | #F5F0E6 | Primary background |
|
| 19 |
+
| Paper Texture | Warm White | #F5F0E1 | Blueprint effect |
|
| 20 |
+
| Primary Text | Dark Maroon | #5D3A3A | Headlines, titles |
|
| 21 |
+
| Body Text | Near Black | #1A1A1A | Content text |
|
| 22 |
+
| Accent 1 | Teal | #2F7373 | Primary illustrations |
|
| 23 |
+
| Accent 2 | Warm Brown | #8B7355 | Secondary elements |
|
| 24 |
+
| Accent 3 | Maroon | #722F37 | Emphasis |
|
| 25 |
+
| Outline | Deep Charcoal | #2D2D2D | Element outlines |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- Isometric 3D or flat 2D technical diagrams
|
| 30 |
+
- Explanatory text boxes with labeled content
|
| 31 |
+
- Bilingual callout labels (English + Chinese)
|
| 32 |
+
- Faded thematic background patterns
|
| 33 |
+
- Clean black outlines on elements
|
| 34 |
+
- Split or triptych layouts
|
| 35 |
+
- Key insight boxes
|
| 36 |
+
|
| 37 |
+
## Style Rules
|
| 38 |
+
|
| 39 |
+
### Do
|
| 40 |
+
|
| 41 |
+
- Include multiple text boxes with content
|
| 42 |
+
- Use bilingual labels for key elements
|
| 43 |
+
- Add faded thematic background patterns
|
| 44 |
+
- Maintain aged paper texture
|
| 45 |
+
- Create clear visual hierarchy
|
| 46 |
+
|
| 47 |
+
### Don't
|
| 48 |
+
|
| 49 |
+
- Create photorealistic 3D renders
|
| 50 |
+
- Leave illustrations without explanatory text
|
| 51 |
+
- Add stamps or watermarks in corners
|
| 52 |
+
- Use gradients or glossy effects
|
| 53 |
+
- Make it look too modern/digital
|
| 54 |
+
|
| 55 |
+
## Best For
|
| 56 |
+
|
| 57 |
+
Technical explanations, concept breakdowns, academic content, research summaries, bilingual audiences, knowledge documentation
|
optional-skills/creative/baoyu-article-illustrator/references/styles/minimal.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# minimal
|
| 2 |
+
|
| 3 |
+
Ultra-clean, zen-like illustration style for focused content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Maximum simplicity with purposeful restraint. Every element serves a function. Zen-like calm and focus through extensive negative space. Single focal point approach that guides attention naturally. Quiet elegance through reduction.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Pure White (#FFFFFF) or Off-White (#FAFAFA)
|
| 12 |
+
- Texture: None - clean solid backgrounds
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | White | #FFFFFF | Primary background |
|
| 19 |
+
| Alt Background | Off-White | #FAFAFA | Subtle variation |
|
| 20 |
+
| Primary | Pure Black | #000000 | Main elements |
|
| 21 |
+
| Accent | Content-Derived | varies | Single accent color |
|
| 22 |
+
| Text | Black | #000000 | Text elements |
|
| 23 |
+
| Alt Text | Medium Gray | #6B6B6B | Secondary text |
|
| 24 |
+
|
| 25 |
+
Note: Accent color is derived from content context. Use sparingly.
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- Single focal element per illustration
|
| 30 |
+
- Maximum negative space
|
| 31 |
+
- Thin, precise lines
|
| 32 |
+
- Simple geometric forms
|
| 33 |
+
- Subtle shadows if any
|
| 34 |
+
- Typography as primary element
|
| 35 |
+
- Strategic use of single accent
|
| 36 |
+
- Clean, uncluttered compositions
|
| 37 |
+
|
| 38 |
+
## Style Rules
|
| 39 |
+
|
| 40 |
+
### Do
|
| 41 |
+
|
| 42 |
+
- Embrace empty space
|
| 43 |
+
- Use single focal points
|
| 44 |
+
- Keep lines thin and precise
|
| 45 |
+
- Let content breathe
|
| 46 |
+
- Question every element
|
| 47 |
+
|
| 48 |
+
### Don't
|
| 49 |
+
|
| 50 |
+
- Add decorative elements
|
| 51 |
+
- Use multiple accent colors
|
| 52 |
+
- Fill available space
|
| 53 |
+
- Add textures or patterns
|
| 54 |
+
- Create visual complexity
|
| 55 |
+
|
| 56 |
+
## Best For
|
| 57 |
+
|
| 58 |
+
Philosophy articles, minimalism content, focused explanations, meditation and mindfulness, essential concepts, clarity-focused writing
|
optional-skills/creative/baoyu-article-illustrator/references/styles/nature.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# nature
|
| 2 |
+
|
| 3 |
+
Organic, earthy illustration style for environmental and wellness content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Natural and organic visual approach inspired by the outdoors. Earth tones and natural textures that evoke calm and connection to nature. Flowing lines and organic shapes. Creates a sense of tranquility and environmental awareness.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Sand Beige (#F5E6D3) or Sky Blue wash (#E0F2FE)
|
| 12 |
+
- Texture: Natural paper texture with organic feel
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Sand Beige | #F5E6D3 | Primary background |
|
| 19 |
+
| Alt Background | Sky Blue | #E0F2FE | Alternative canvas |
|
| 20 |
+
| Primary | Forest Green | #276749 | Main natural color |
|
| 21 |
+
| Secondary | Sage | #9AE6B4 | Supporting green |
|
| 22 |
+
| Tertiary | Earth Brown | #744210 | Grounding element |
|
| 23 |
+
| Accent 1 | Sunset Orange | #ED8936 | Warm accent |
|
| 24 |
+
| Accent 2 | Water Blue | #63B3ED | Cool accent |
|
| 25 |
+
| Text | Deep Brown | #5D4E3C | Text elements |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- Leaf and plant motifs
|
| 30 |
+
- Tree and branch silhouettes
|
| 31 |
+
- Mountain and landscape shapes
|
| 32 |
+
- Organic flowing lines
|
| 33 |
+
- Natural textures (wood grain, stone)
|
| 34 |
+
- Water and wave patterns
|
| 35 |
+
- Animal silhouettes
|
| 36 |
+
- Sun and moon symbols
|
| 37 |
+
|
| 38 |
+
## Style Rules
|
| 39 |
+
|
| 40 |
+
### Do
|
| 41 |
+
|
| 42 |
+
- Use earth-inspired colors
|
| 43 |
+
- Create organic, flowing shapes
|
| 44 |
+
- Include nature elements
|
| 45 |
+
- Evoke outdoor atmosphere
|
| 46 |
+
- Maintain calm and balance
|
| 47 |
+
|
| 48 |
+
### Don't
|
| 49 |
+
|
| 50 |
+
- Use synthetic or neon colors
|
| 51 |
+
- Create rigid geometric shapes
|
| 52 |
+
- Add tech or digital elements
|
| 53 |
+
- Use stark contrasts
|
| 54 |
+
- Overcomplicate compositions
|
| 55 |
+
|
| 56 |
+
## Best For
|
| 57 |
+
|
| 58 |
+
Sustainability articles, wellness content, outdoor topics, slow living, environmental issues, health and fitness, gardening, travel nature pieces
|
optional-skills/creative/baoyu-article-illustrator/references/styles/notion.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# notion
|
| 2 |
+
|
| 3 |
+
Minimalist hand-drawn line art style for knowledge content (Default)
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Clean, minimalist hand-drawn line art with intellectual feel. Simple doodle-style illustrations with intentional wobble. Maximum whitespace with single concept focus. Notion-like aesthetic that feels thoughtful and organized.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Pure White (#FFFFFF) or Off-White (#FAFAFA)
|
| 12 |
+
- Texture: None - clean solid backgrounds
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | White | #FFFFFF | Primary background |
|
| 19 |
+
| Alt Background | Off-White | #FAFAFA | Subtle variation |
|
| 20 |
+
| Primary | Black | #1A1A1A | Main outlines |
|
| 21 |
+
| Secondary | Dark Gray | #4A4A4A | Supporting lines |
|
| 22 |
+
| Accent 1 | Pastel Blue | #A8D4F0 | Soft highlight |
|
| 23 |
+
| Accent 2 | Pastel Yellow | #F9E79F | Warm highlight |
|
| 24 |
+
| Accent 3 | Pastel Pink | #FADBD8 | Gentle accent |
|
| 25 |
+
| Text | Near Black | #1A1A1A | Text elements |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- Simple line doodles
|
| 30 |
+
- Hand-drawn wobble effect
|
| 31 |
+
- Basic geometric shapes
|
| 32 |
+
- Stick figures for people
|
| 33 |
+
- Conceptual icons
|
| 34 |
+
- Clean hand-drawn lettering
|
| 35 |
+
- Minimal decorative elements
|
| 36 |
+
- Single-weight line work
|
| 37 |
+
|
| 38 |
+
## Style Rules
|
| 39 |
+
|
| 40 |
+
### Do
|
| 41 |
+
|
| 42 |
+
- Use maximum whitespace
|
| 43 |
+
- Keep illustrations simple
|
| 44 |
+
- Add slight hand-drawn wobble
|
| 45 |
+
- Focus on single concepts
|
| 46 |
+
- Use pastel accents sparingly
|
| 47 |
+
|
| 48 |
+
### Don't
|
| 49 |
+
|
| 50 |
+
- Create complex illustrations
|
| 51 |
+
- Use many colors at once
|
| 52 |
+
- Add detailed textures
|
| 53 |
+
- Make precise geometric shapes
|
| 54 |
+
- Overcrowd the composition
|
| 55 |
+
|
| 56 |
+
## Best For
|
| 57 |
+
|
| 58 |
+
Knowledge sharing, concept explanations, SaaS content, productivity articles, educational posts, how-to guides, professional blogs
|
optional-skills/creative/baoyu-article-illustrator/references/styles/pixel-art.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# pixel-art
|
| 2 |
+
|
| 3 |
+
Retro 8-bit pixel art aesthetic with nostalgic gaming style
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Pixelated retro aesthetic reminiscent of classic 8-bit and 16-bit era games. Chunky pixels, limited color palettes, and nostalgic gaming references. Simple geometric shapes rendered in blocky pixel form. Fun, playful, and immediately recognizable retro tech aesthetic.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Light Blue (#87CEEB) or Soft Lavender (#E6E6FA)
|
| 12 |
+
- Texture: Subtle pixel grid pattern, optional CRT scanline effect
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Light Blue | #87CEEB | Primary background |
|
| 19 |
+
| Alt Background | Soft Lavender | #E6E6FA | Secondary backgrounds |
|
| 20 |
+
| Primary Text | Dark Navy | #1A1A2E | Main elements |
|
| 21 |
+
| Accent 1 | Pixel Green | #00FF00 | Success, highlights |
|
| 22 |
+
| Accent 2 | Pixel Red | #FF0000 | Alerts, emphasis |
|
| 23 |
+
| Accent 3 | Pixel Yellow | #FFFF00 | Warnings, energy |
|
| 24 |
+
| Accent 4 | Pixel Cyan | #00FFFF | Info, tech elements |
|
| 25 |
+
| Accent 5 | Pixel Magenta | #FF00FF | Special elements |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- All elements rendered with visible pixel structure
|
| 30 |
+
- Simple iconography: notepad, checkboxes, gears, rockets
|
| 31 |
+
- Text bubbles with pixel borders
|
| 32 |
+
- 8-bit decorations: stars, hearts, arrows
|
| 33 |
+
- Progress bars with chunky pixel segments
|
| 34 |
+
- Dithering patterns for color transitions
|
| 35 |
+
- Limited 16-32 color palette
|
| 36 |
+
|
| 37 |
+
## Style Rules
|
| 38 |
+
|
| 39 |
+
### Do
|
| 40 |
+
|
| 41 |
+
- Maintain consistent pixel grid throughout
|
| 42 |
+
- Use limited color palette (16-32 colors max)
|
| 43 |
+
- Create blocky, geometric shapes
|
| 44 |
+
- Add nostalgic gaming references
|
| 45 |
+
- Use dithering for color transitions
|
| 46 |
+
|
| 47 |
+
### Don't
|
| 48 |
+
|
| 49 |
+
- Use smooth gradients or anti-aliasing
|
| 50 |
+
- Create photorealistic elements
|
| 51 |
+
- Use thin lines or fine details
|
| 52 |
+
- Add modern glossy effects
|
| 53 |
+
- Break the pixel grid alignment
|
| 54 |
+
|
| 55 |
+
## Best For
|
| 56 |
+
|
| 57 |
+
Gaming articles, tech tutorials, nostalgic content, developer topics, retro-themed pieces, creative tech content
|
optional-skills/creative/baoyu-article-illustrator/references/styles/playful.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# playful
|
| 2 |
+
|
| 3 |
+
Fun, creative illustration style for casual and educational content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Whimsical and entertaining visual approach that sparks joy. Pastel colors with bright pops of energy. Doodle-like quality that feels approachable and fun. Creates a sense of play and discovery. Encourages engagement through visual delight.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Light Cream (#FFFBEB) or Soft White (#FFF)
|
| 12 |
+
- Texture: Subtle, playful pattern or clean
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Light Cream | #FFFBEB | Primary background |
|
| 19 |
+
| Primary | Pastel Pink | #FED7E2 | Soft warmth |
|
| 20 |
+
| Secondary | Mint | #C6F6D5 | Fresh energy |
|
| 21 |
+
| Tertiary | Lavender | #E9D8FD | Dreamy touch |
|
| 22 |
+
| Accent 1 | Sky Blue | #BEE3F8 | Calm brightness |
|
| 23 |
+
| Accent 2 | Bright Yellow | #FBBF24 | Energy pop |
|
| 24 |
+
| Accent 3 | Coral | #F6AD55 | Warm pop |
|
| 25 |
+
| Accent 4 | Turquoise | #38B2AC | Cool pop |
|
| 26 |
+
| Text | Soft Charcoal | #4A4A4A | Text elements |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Doodles and sketchy lines
|
| 31 |
+
- Star and sparkle decorations
|
| 32 |
+
- Swirls and curvy elements
|
| 33 |
+
- Cute character illustrations
|
| 34 |
+
- Speech bubbles and callouts
|
| 35 |
+
- Emoji-style icons
|
| 36 |
+
- Confetti and celebration marks
|
| 37 |
+
- Playful hand-lettering
|
| 38 |
+
|
| 39 |
+
## Style Rules
|
| 40 |
+
|
| 41 |
+
### Do
|
| 42 |
+
|
| 43 |
+
- Use varied pastel palette
|
| 44 |
+
- Add whimsical decorations
|
| 45 |
+
- Create friendly characters
|
| 46 |
+
- Include playful details
|
| 47 |
+
- Keep energy high and positive
|
| 48 |
+
|
| 49 |
+
### Don't
|
| 50 |
+
|
| 51 |
+
- Use dark or moody colors
|
| 52 |
+
- Create serious compositions
|
| 53 |
+
- Add corporate elements
|
| 54 |
+
- Use rigid geometric shapes
|
| 55 |
+
- Make it feel professional
|
| 56 |
+
|
| 57 |
+
## Best For
|
| 58 |
+
|
| 59 |
+
Tutorials and guides, beginner-friendly content, casual articles, fun topics, children's content, hobby-related posts, entertaining explanations
|
optional-skills/creative/baoyu-article-illustrator/references/styles/retro.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# retro
|
| 2 |
+
|
| 3 |
+
80s/90s nostalgic aesthetic with vibrant colors and geometric patterns
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Nostalgic retro aesthetic inspired by 80s and 90s design trends. Vibrant neon colors, geometric patterns, and Memphis design influence. Energetic, fun, and unapologetically bold. Perfect for content that embraces nostalgia or playful energy.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Deep Purple (#2D1B4E) or Dark Teal (#0F4C5C)
|
| 12 |
+
- Texture: Subtle grid patterns or geometric shapes
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Deep Purple | #2D1B4E | Primary background |
|
| 19 |
+
| Alt Background | Dark Teal | #0F4C5C | Alternative |
|
| 20 |
+
| Primary | Hot Pink | #FF1493 | Main accent |
|
| 21 |
+
| Secondary | Electric Cyan | #00FFFF | Supporting |
|
| 22 |
+
| Tertiary | Neon Yellow | #FFFF00 | Highlights |
|
| 23 |
+
| Accent 1 | Lime Green | #32CD32 | Energy |
|
| 24 |
+
| Accent 2 | Orange | #FF6B35 | Warmth |
|
| 25 |
+
| Text | White | #FFFFFF | Text elements |
|
| 26 |
+
| Grid | Light Purple | #9D8EC0 | Grid lines |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Geometric patterns (triangles, circles)
|
| 31 |
+
- Grid backgrounds and lines
|
| 32 |
+
- Neon glow effects
|
| 33 |
+
- Memphis design shapes
|
| 34 |
+
- Zigzag and wavy patterns
|
| 35 |
+
- Retro computer graphics
|
| 36 |
+
- Bold outline strokes
|
| 37 |
+
- Gradient sunsets
|
| 38 |
+
|
| 39 |
+
## Style Rules
|
| 40 |
+
|
| 41 |
+
### Do
|
| 42 |
+
|
| 43 |
+
- Use bold neon colors
|
| 44 |
+
- Create geometric patterns
|
| 45 |
+
- Add retro typography
|
| 46 |
+
- Include Memphis-style shapes
|
| 47 |
+
- Embrace maximalism
|
| 48 |
+
|
| 49 |
+
### Don't
|
| 50 |
+
|
| 51 |
+
- Use muted or subtle colors
|
| 52 |
+
- Create minimal compositions
|
| 53 |
+
- Add modern flat design
|
| 54 |
+
- Make it look contemporary
|
| 55 |
+
- Use understated elements
|
| 56 |
+
|
| 57 |
+
## Best For
|
| 58 |
+
|
| 59 |
+
Pop culture articles, gaming content, music and entertainment, nostalgia pieces, youth-focused content, creative industry, party and event content
|
optional-skills/creative/baoyu-article-illustrator/references/styles/scientific.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# scientific
|
| 2 |
+
|
| 3 |
+
Academic scientific illustration style for technical diagrams and processes
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Academic scientific illustration aesthetic for biological, chemical, and technical diagrams. Clean, precise diagrams with proper labeling and clear visual flow. Educational clarity with professional polish. Textbook quality illustrations.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Off-White (#FAFAFA) or Light Blue-Gray (#F0F4F8)
|
| 12 |
+
- Texture: None or subtle paper grain
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Off-White | #FAFAFA | Primary background |
|
| 19 |
+
| Primary Text | Dark Slate | #1E293B | Labels, headers |
|
| 20 |
+
| Label Text | Medium Gray | #475569 | Annotations |
|
| 21 |
+
| Pathway 1 | Teal | #0D9488 | Primary pathway |
|
| 22 |
+
| Pathway 2 | Blue | #3B82F6 | Secondary pathway |
|
| 23 |
+
| Pathway 3 | Purple | #8B5CF6 | Tertiary pathway |
|
| 24 |
+
| Structure | Amber | #F59E0B | Membranes, structures |
|
| 25 |
+
| Alert | Red | #EF4444 | Key elements |
|
| 26 |
+
| Positive | Green | #22C55E | Products, outputs |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Precise labeled diagrams
|
| 31 |
+
- Flow arrows showing direction
|
| 32 |
+
- Modular components with colors
|
| 33 |
+
- Chemical formulas and notation
|
| 34 |
+
- Cross-section views
|
| 35 |
+
- Numbered step sequences
|
| 36 |
+
- Molecule and cell representations
|
| 37 |
+
- Process summary boxes
|
| 38 |
+
|
| 39 |
+
## Style Rules
|
| 40 |
+
|
| 41 |
+
### Do
|
| 42 |
+
|
| 43 |
+
- Use precise consistent lines
|
| 44 |
+
- Label all components clearly
|
| 45 |
+
- Show directional flow
|
| 46 |
+
- Include technical notation
|
| 47 |
+
- Create clear numbered sequences
|
| 48 |
+
|
| 49 |
+
### Don't
|
| 50 |
+
|
| 51 |
+
- Use decorative elements
|
| 52 |
+
- Create imprecise diagrams
|
| 53 |
+
- Omit important labels
|
| 54 |
+
- Use inconsistent styling
|
| 55 |
+
- Add artistic flourishes
|
| 56 |
+
|
| 57 |
+
## Best For
|
| 58 |
+
|
| 59 |
+
Biology articles, chemistry explanations, medical content, research summaries, academic writing, technical documentation, process explanations
|
optional-skills/creative/baoyu-article-illustrator/references/styles/screen-print.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# screen-print
|
| 2 |
+
|
| 3 |
+
Bold poster art with limited colors, halftone textures, and symbolic storytelling
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Screen print / silkscreen aesthetic inspired by Mondo limited-edition posters and vintage concert prints. Flat color blocks, halftone dot patterns, bold silhouettes, and deliberate print imperfections. Conceptual and symbolic rather than literal — one iconic image tells the whole story. Perfect for opinion pieces, cultural commentary, and editorial content.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Off-Black (#121212) or Warm Cream (#F5E6D0)
|
| 12 |
+
- Texture: Paper grain with subtle halftone dot overlay
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Off-Black | #121212 | Dark compositions |
|
| 19 |
+
| Background Alt | Warm Cream | #F5E6D0 | Light compositions |
|
| 20 |
+
| Primary | Burnt Orange | #E8751A | Main accent |
|
| 21 |
+
| Secondary | Deep Teal | #0A6E6E | Contrast accent |
|
| 22 |
+
| Tertiary | Crimson | #C0392B | Bold emphasis |
|
| 23 |
+
| Highlight | Amber | #F4A623 | Small accents |
|
| 24 |
+
| Text | Cream White | #FAF3E0 | On dark backgrounds |
|
| 25 |
+
|
| 26 |
+
**Duotone Pairs** (choose ONE pair for high-impact compositions):
|
| 27 |
+
|
| 28 |
+
| Pair | Color A | Color B | Feel |
|
| 29 |
+
|------|---------|---------|------|
|
| 30 |
+
| Orange + Teal | #E8751A | #0A6E6E | Cinematic, action |
|
| 31 |
+
| Red + Cream | #C0392B | #F5E6D0 | Bold, classic |
|
| 32 |
+
| Blue + Gold | #1A3A5C | #D4A843 | Prestigious, premium |
|
| 33 |
+
| Crimson + Navy | #DC143C | #0D1B2A | Dramatic, noir |
|
| 34 |
+
|
| 35 |
+
**Rule**: Use 2-5 colors maximum. Fewer colors = stronger impact.
|
| 36 |
+
|
| 37 |
+
## Visual Elements
|
| 38 |
+
|
| 39 |
+
- Bold silhouettes and symbolic shapes
|
| 40 |
+
- Halftone dot patterns within color fills
|
| 41 |
+
- Slight color layer misregistration (print offset effect)
|
| 42 |
+
- Geometric framing (circles, arches, triangles)
|
| 43 |
+
- Figure-ground inversion (negative space forms secondary image)
|
| 44 |
+
- Stencil-cut edges, no outlines — shapes defined by color boundaries
|
| 45 |
+
- Typography integrated as design element, not overlay
|
| 46 |
+
- Vintage poster border treatments
|
| 47 |
+
|
| 48 |
+
## Style Rules
|
| 49 |
+
|
| 50 |
+
### Do
|
| 51 |
+
|
| 52 |
+
- Limit to 2-5 flat colors
|
| 53 |
+
- Use bold silhouettes over detailed rendering
|
| 54 |
+
- Let negative space tell part of the story
|
| 55 |
+
- Add halftone texture for authenticity
|
| 56 |
+
- Use geometric composition (centered, symmetrical)
|
| 57 |
+
- Reference vintage decades (60s/70s/80s) for era feel
|
| 58 |
+
|
| 59 |
+
### Don't
|
| 60 |
+
|
| 61 |
+
- Use photorealistic rendering or gradients
|
| 62 |
+
- Add complex facial details (silhouettes preferred)
|
| 63 |
+
- Mix too many visual elements (one focal point)
|
| 64 |
+
- Use modern digital aesthetic
|
| 65 |
+
- Create busy or cluttered compositions
|
| 66 |
+
- Use more than 5 colors
|
| 67 |
+
|
| 68 |
+
## Best For
|
| 69 |
+
|
| 70 |
+
Opinion/editorial articles, cultural commentary, philosophy and strategy, dramatic narratives, cinematic storytelling, music and entertainment, event announcements, bold branding content
|
optional-skills/creative/baoyu-article-illustrator/references/styles/sketch-notes.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# sketch-notes
|
| 2 |
+
|
| 3 |
+
Soft hand-drawn illustration style with warm, educational feel
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Hand-drawn feel with soft, relaxed brush strokes. Fresh, refined style with minimalist editorial approach. Emphasis on precision, clarity and intelligent elegance while prioritizing warmth, approachability and friendliness.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Warm Off-White (#FAF8F0)
|
| 12 |
+
- Texture: Subtle paper grain, warm tone
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Warm Off-White | #FAF8F0 | Primary background |
|
| 19 |
+
| Primary Text | Deep Charcoal | #2C3E50 | Main elements |
|
| 20 |
+
| Alt Text | Deep Brown | #4A4A4A | Secondary elements |
|
| 21 |
+
| Accent 1 | Soft Orange | #F4A261 | Highlights, emphasis |
|
| 22 |
+
| Accent 2 | Mustard Yellow | #E9C46A | Secondary highlights |
|
| 23 |
+
| Accent 3 | Sage Green | #87A96B | Nature, growth concepts |
|
| 24 |
+
| Accent 4 | Light Blue | #7EC8E3 | Tech, digital elements |
|
| 25 |
+
| Accent 5 | Red Brown | #A0522D | Earthy elements |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- Connection lines with hand-drawn wavy feel
|
| 30 |
+
- Conceptual abstract icons illustrating ideas
|
| 31 |
+
- Color fills don't completely fill outlines (hand-painted feel)
|
| 32 |
+
- Simple geometric shapes with rounded corners
|
| 33 |
+
- Arrows and pointers with sketchy style
|
| 34 |
+
- Doodle decorations: stars, spirals, underlines
|
| 35 |
+
|
| 36 |
+
## Style Rules
|
| 37 |
+
|
| 38 |
+
### Do
|
| 39 |
+
|
| 40 |
+
- Keep layouts open and well-structured
|
| 41 |
+
- Emphasize information hierarchy
|
| 42 |
+
- Use hand-drawn quality for all elements
|
| 43 |
+
- Allow imperfection (slight wobbles add character)
|
| 44 |
+
- Layer elements with subtle overlaps
|
| 45 |
+
|
| 46 |
+
### Don't
|
| 47 |
+
|
| 48 |
+
- Use perfect geometric shapes
|
| 49 |
+
- Create photorealistic elements
|
| 50 |
+
- Overcrowd with too many elements
|
| 51 |
+
- Use pure white backgrounds
|
| 52 |
+
- Make it look computer-generated
|
| 53 |
+
|
| 54 |
+
## Best For
|
| 55 |
+
|
| 56 |
+
Educational content, knowledge sharing, technical explanations, tutorials, onboarding materials, friendly articles
|
optional-skills/creative/baoyu-article-illustrator/references/styles/sketch.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# sketch
|
| 2 |
+
|
| 3 |
+
Raw, authentic notebook-style illustration for ideas and processes
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Hand-drawn sketch aesthetic that feels authentic and in-progress. Pencil-on-paper quality with intentional imperfection. Suggests thinking, brainstorming, and creative exploration. Raw and honest visual approach that invites collaboration.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Off-White Paper (#F7FAFC) or Cream (#FAFAFA)
|
| 12 |
+
- Texture: Paper texture with visible grain
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Paper White | #F7FAFC | Primary background |
|
| 19 |
+
| Primary | Pencil Gray | #4A5568 | Main sketch lines |
|
| 20 |
+
| Secondary | Light Gray | #A0AEC0 | Shading, soft marks |
|
| 21 |
+
| Highlight Blue | Note Blue | #3182CE | Highlight color |
|
| 22 |
+
| Highlight Red | Mark Red | #E53E3E | Emphasis color |
|
| 23 |
+
| Highlight Yellow | Marker Yellow | #F6E05E | Highlighter effect |
|
| 24 |
+
| Text | Charcoal | #2D3748 | Text elements |
|
| 25 |
+
|
| 26 |
+
## Visual Elements
|
| 27 |
+
|
| 28 |
+
- Rough sketch lines with natural variation
|
| 29 |
+
- Arrows and directional pointers
|
| 30 |
+
- Handwritten labels and notes
|
| 31 |
+
- Crossed-out marks and corrections
|
| 32 |
+
- Underlines and emphasis marks
|
| 33 |
+
- Simple diagram shapes
|
| 34 |
+
- Margin notes style
|
| 35 |
+
- Quick icon sketches
|
| 36 |
+
|
| 37 |
+
## Style Rules
|
| 38 |
+
|
| 39 |
+
### Do
|
| 40 |
+
|
| 41 |
+
- Use pencil-like line quality
|
| 42 |
+
- Include natural imperfections
|
| 43 |
+
- Add handwritten annotations
|
| 44 |
+
- Create diagram-style layouts
|
| 45 |
+
- Show thinking process
|
| 46 |
+
|
| 47 |
+
### Don't
|
| 48 |
+
|
| 49 |
+
- Use perfect geometric shapes
|
| 50 |
+
- Add polished or refined elements
|
| 51 |
+
- Create colorful compositions
|
| 52 |
+
- Use digital effects
|
| 53 |
+
- Make it look finished
|
| 54 |
+
|
| 55 |
+
## Best For
|
| 56 |
+
|
| 57 |
+
Ideas in progress, brainstorming articles, thought processes, concept exploration, draft-stage thinking, planning content, problem-solving pieces
|
optional-skills/creative/baoyu-article-illustrator/references/styles/vector-illustration.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# vector-illustration
|
| 2 |
+
|
| 3 |
+
Flat vector illustration style with clear black outlines and retro soft colors
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Flat vector illustration with no gradients or 3D effects. Clear, uniform-thickness black outlines on all elements. Geometric simplification reducing complex objects to basic shapes. Toy model aesthetic that's cute, playful, and approachable. Coloring book style with closed outlines.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Cream Off-White (#F5F0E6)
|
| 12 |
+
- Texture: Subtle paper texture, warm nostalgic feel
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Cream Off-White | #F5F0E6 | Primary background |
|
| 19 |
+
| Outlines | Deep Charcoal | #2D2D2D | All element outlines |
|
| 20 |
+
| Primary | Coral Red | #E07A5F | Primary accent, warmth |
|
| 21 |
+
| Secondary | Mint Green | #81B29A | Nature, growth |
|
| 22 |
+
| Tertiary | Mustard Yellow | #F2CC8F | Highlights, energy |
|
| 23 |
+
| Accent 1 | Burnt Orange | #D4764A | Warm accents |
|
| 24 |
+
| Accent 2 | Rock Blue | #577590 | Cool balance |
|
| 25 |
+
| Text | Black | #1A1A1A | Text elements |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- All objects have closed black outlines (coloring book style)
|
| 30 |
+
- Rounded line endings, avoid sharp corners
|
| 31 |
+
- Trees simplified to lollipop or triangle shapes
|
| 32 |
+
- Buildings as rectangular blocks with grid windows
|
| 33 |
+
- Depth through layering and overlap
|
| 34 |
+
- Decorative elements: sunbursts, pill-shaped clouds, dots, stars
|
| 35 |
+
- People as simple geometric figures
|
| 36 |
+
|
| 37 |
+
## Style Rules
|
| 38 |
+
|
| 39 |
+
### Do
|
| 40 |
+
|
| 41 |
+
- Maintain consistent outline thickness
|
| 42 |
+
- Use soft, vintage color palette
|
| 43 |
+
- Simplify objects to basic geometric shapes
|
| 44 |
+
- Create depth through layering
|
| 45 |
+
- Add playful decorative elements
|
| 46 |
+
|
| 47 |
+
### Don't
|
| 48 |
+
|
| 49 |
+
- Use gradients or realistic shading
|
| 50 |
+
- Create photorealistic elements
|
| 51 |
+
- Use thin or varying line weights
|
| 52 |
+
- Include complex detailed illustrations
|
| 53 |
+
- Add textures inside shapes
|
| 54 |
+
|
| 55 |
+
## Best For
|
| 56 |
+
|
| 57 |
+
Educational content, creative articles, children's content, brand showcases, explainer pieces, warm approachable topics
|
optional-skills/creative/baoyu-article-illustrator/references/styles/vintage.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# vintage
|
| 2 |
+
|
| 3 |
+
Nostalgic aged-paper aesthetic for historical and heritage content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Nostalgic vintage aesthetic with aged paper textures and historical document styling. Explorer's journal and antique map quality. Rich warm tones with weathered textures. Evokes discovery, heritage, and timeless knowledge.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Aged Parchment (#F5E6D3) or Sepia Cream (#FFF8DC)
|
| 12 |
+
- Texture: Heavy aged paper texture with subtle stains and worn edges
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Aged Parchment | #F5E6D3 | Primary background |
|
| 19 |
+
| Alt Background | Sepia Cream | #FFF8DC | Secondary areas |
|
| 20 |
+
| Primary Text | Dark Brown | #3D2914 | Main elements |
|
| 21 |
+
| Secondary | Medium Brown | #6B4423 | Supporting details |
|
| 22 |
+
| Accent 1 | Forest Green | #2D5A3D | Nature, maps |
|
| 23 |
+
| Accent 2 | Navy Blue | #1E3A5F | Ocean, lines |
|
| 24 |
+
| Accent 3 | Burgundy | #722F37 | Emphasis |
|
| 25 |
+
| Accent 4 | Gold | #C9A227 | Highlights |
|
| 26 |
+
| Ink | Sepia Black | #3D3D3D | Fine details |
|
| 27 |
+
|
| 28 |
+
## Visual Elements
|
| 29 |
+
|
| 30 |
+
- Antique map styling with route lines
|
| 31 |
+
- Compass roses and navigation elements
|
| 32 |
+
- Specimen-style drawings
|
| 33 |
+
- Handwritten annotations
|
| 34 |
+
- Rope, leather, brass decorative motifs
|
| 35 |
+
- Vintage photograph frames
|
| 36 |
+
- Aged paper edge effects
|
| 37 |
+
- Historical document styling
|
| 38 |
+
|
| 39 |
+
## Style Rules
|
| 40 |
+
|
| 41 |
+
### Do
|
| 42 |
+
|
| 43 |
+
- Apply consistent aged texture
|
| 44 |
+
- Use period-appropriate styling
|
| 45 |
+
- Include map and journey elements
|
| 46 |
+
- Create layered compositions
|
| 47 |
+
- Maintain warm sepia tones
|
| 48 |
+
|
| 49 |
+
### Don't
|
| 50 |
+
|
| 51 |
+
- Use modern digital styling
|
| 52 |
+
- Create crisp clean edges
|
| 53 |
+
- Use cold or bright colors
|
| 54 |
+
- Add contemporary elements
|
| 55 |
+
- Make it look new or fresh
|
| 56 |
+
|
| 57 |
+
## Best For
|
| 58 |
+
|
| 59 |
+
Historical articles, travel and exploration, biography pieces, heritage stories, scientific discovery narratives, museum-style content, classic literature references
|
optional-skills/creative/baoyu-article-illustrator/references/styles/warm.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# warm
|
| 2 |
+
|
| 3 |
+
Friendly, approachable illustration style for human-centered content
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Warm and inviting visual approach that feels personal and approachable. Soft, friendly colors that evoke comfort and connection. Emphasizes human elements and emotional resonance. Creates an atmosphere of trust and openness.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Cream (#FFFAF0) or Soft Peach (#FED7AA)
|
| 12 |
+
- Texture: Soft paper texture with warm undertones
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Cream | #FFFAF0 | Primary background |
|
| 19 |
+
| Alt Background | Soft Peach | #FED7AA | Accent sections |
|
| 20 |
+
| Primary | Warm Orange | #ED8936 | Main accent color |
|
| 21 |
+
| Secondary | Golden Yellow | #F6AD55 | Supporting warmth |
|
| 22 |
+
| Tertiary | Terracotta | #C05621 | Earthy depth |
|
| 23 |
+
| Accent | Deep Brown | #744210 | Grounding elements |
|
| 24 |
+
| Alt Accent | Soft Red | #E53E3E | Emotional touches |
|
| 25 |
+
| Text | Warm Charcoal | #4A4A4A | Text elements |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- Rounded shapes and soft corners
|
| 30 |
+
- Friendly character illustrations
|
| 31 |
+
- Sun rays and warm light motifs
|
| 32 |
+
- Heart symbols and care icons
|
| 33 |
+
- Cozy lighting effects
|
| 34 |
+
- Gentle gradients with warmth
|
| 35 |
+
- Soft shadows without harsh edges
|
| 36 |
+
- Hand-drawn quality touches
|
| 37 |
+
|
| 38 |
+
## Style Rules
|
| 39 |
+
|
| 40 |
+
### Do
|
| 41 |
+
|
| 42 |
+
- Use warm, inviting colors
|
| 43 |
+
- Create rounded, friendly shapes
|
| 44 |
+
- Include human-centered elements
|
| 45 |
+
- Evoke feelings of comfort
|
| 46 |
+
- Maintain soft, gentle contrasts
|
| 47 |
+
|
| 48 |
+
### Don't
|
| 49 |
+
|
| 50 |
+
- Use cold or stark colors
|
| 51 |
+
- Create sharp, aggressive shapes
|
| 52 |
+
- Add technical or clinical elements
|
| 53 |
+
- Use dark, moody backgrounds
|
| 54 |
+
- Create sterile compositions
|
| 55 |
+
|
| 56 |
+
## Best For
|
| 57 |
+
|
| 58 |
+
Personal growth articles, lifestyle content, education, human interest stories, wellness topics, relationship advice, self-help content, community building
|
optional-skills/creative/baoyu-article-illustrator/references/styles/watercolor.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# watercolor
|
| 2 |
+
|
| 3 |
+
Soft, artistic watercolor illustration style with natural warmth
|
| 4 |
+
|
| 5 |
+
## Design Aesthetic
|
| 6 |
+
|
| 7 |
+
Gentle watercolor aesthetic with visible brush strokes and natural color bleeding. Hand-painted feel with soft edges and organic shapes. Warm, approachable, and artistically refined. Combines artistic expression with clear visual communication.
|
| 8 |
+
|
| 9 |
+
## Background
|
| 10 |
+
|
| 11 |
+
- Color: Warm Off-White (#FAF8F0) or Soft Cream (#FFF9E6)
|
| 12 |
+
- Texture: Subtle watercolor paper texture with visible grain
|
| 13 |
+
|
| 14 |
+
## Color Palette
|
| 15 |
+
|
| 16 |
+
| Role | Color | Hex | Usage |
|
| 17 |
+
|------|-------|-----|-------|
|
| 18 |
+
| Background | Warm Off-White | #FAF8F0 | Primary background |
|
| 19 |
+
| Primary | Soft Coral | #F4A261 | Primary warmth |
|
| 20 |
+
| Secondary | Dusty Rose | #E8A0A0 | Secondary warmth |
|
| 21 |
+
| Tertiary | Sage Green | #87A96B | Nature, growth |
|
| 22 |
+
| Accent 1 | Sky Blue | #7EC8E3 | Water, calm |
|
| 23 |
+
| Accent 2 | Soft Lavender | #C5B4E3 | Accent, creativity |
|
| 24 |
+
| Wash | Pale Yellow | #FFF3C4 | Background washes |
|
| 25 |
+
| Text | Warm Charcoal | #3D3D3D | Text elements |
|
| 26 |
+
|
| 27 |
+
## Visual Elements
|
| 28 |
+
|
| 29 |
+
- Watercolor washes as backgrounds
|
| 30 |
+
- Illustrated elements with visible brush strokes
|
| 31 |
+
- Natural elements: leaves, flowers, bubbles
|
| 32 |
+
- Color bleeds and soft edges
|
| 33 |
+
- Hand-drawn arrows and lines
|
| 34 |
+
- Layered wash effects
|
| 35 |
+
- Soft gradients through water
|
| 36 |
+
- Expressive character illustrations
|
| 37 |
+
|
| 38 |
+
## Style Rules
|
| 39 |
+
|
| 40 |
+
### Do
|
| 41 |
+
|
| 42 |
+
- Allow color to bleed beyond edges
|
| 43 |
+
- Use visible brush stroke textures
|
| 44 |
+
- Create soft, organic shapes
|
| 45 |
+
- Include hand-drawn quality
|
| 46 |
+
- Maintain warm color palette
|
| 47 |
+
|
| 48 |
+
### Don't
|
| 49 |
+
|
| 50 |
+
- Use sharp geometric shapes
|
| 51 |
+
- Create hard digital edges
|
| 52 |
+
- Use cold or stark colors
|
| 53 |
+
- Add photographic elements
|
| 54 |
+
- Create overly precise illustrations
|
| 55 |
+
|
| 56 |
+
## Best For
|
| 57 |
+
|
| 58 |
+
Lifestyle articles, wellness content, travel pieces, food and cooking, personal stories, creative topics, artistic portfolios, warm educational content
|
optional-skills/creative/baoyu-article-illustrator/references/usage.md
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Usage
|
| 2 |
+
|
| 3 |
+
This skill is triggered by natural language in Hermes — no slash command or CLI flags.
|
| 4 |
+
|
| 5 |
+
## Trigger Phrases
|
| 6 |
+
|
| 7 |
+
- "Illustrate this article" / "为文章配图"
|
| 8 |
+
- "Add images to this post"
|
| 9 |
+
- "Generate illustrations for [path/to/article.md]"
|
| 10 |
+
|
| 11 |
+
## Input Modes
|
| 12 |
+
|
| 13 |
+
| Mode | How to trigger | Output Directory |
|
| 14 |
+
|------|----------------|------------------|
|
| 15 |
+
| File path | Mention an article path (`path/to/article.md`) | `{article-dir}/imgs/` (default) |
|
| 16 |
+
| Pasted content | Paste the article text in the conversation | `illustrations/{topic-slug}/` (cwd) |
|
| 17 |
+
|
| 18 |
+
## Specifying Options in Natural Language
|
| 19 |
+
|
| 20 |
+
The user can specify any of the following directly in their request. If not specified, the skill asks via the `clarify` tool.
|
| 21 |
+
|
| 22 |
+
| Option | Example phrasing |
|
| 23 |
+
|--------|------------------|
|
| 24 |
+
| Type | "as an infographic", "as a flowchart", "as scenes" |
|
| 25 |
+
| Style | "in blueprint style", "use notion style", "用 watercolor 风格" |
|
| 26 |
+
| Preset | "use the tech-explainer preset", "storytelling preset" |
|
| 27 |
+
| Palette | "with macaron palette", "warm colors only" |
|
| 28 |
+
| Density | "minimal images", "one per section", "rich illustrations" |
|
| 29 |
+
| Language | "images in English" / "图片文字用中文" |
|
| 30 |
+
| Output | "save images alongside the article" / "put them in `illustrations/`" |
|
| 31 |
+
|
| 32 |
+
## Examples
|
| 33 |
+
|
| 34 |
+
**Technical article with data**:
|
| 35 |
+
> 帮我为 api-design.md 配图,用 infographic + blueprint 风格
|
| 36 |
+
|
| 37 |
+
**Preset shortcut**:
|
| 38 |
+
> Illustrate api-design.md with the tech-explainer preset
|
| 39 |
+
|
| 40 |
+
**Personal story**:
|
| 41 |
+
> Illustrate journey.md using the storytelling preset
|
| 42 |
+
|
| 43 |
+
**Tutorial with rich images**:
|
| 44 |
+
> Generate illustrations for how-to-deploy.md — tutorial preset, rich density
|
| 45 |
+
|
| 46 |
+
**Opinion article**:
|
| 47 |
+
> Illustrate opinion.md with the opinion-piece preset
|
| 48 |
+
|
| 49 |
+
**Preset with style override**:
|
| 50 |
+
> Use the tech-explainer preset for article.md but swap the style for notion
|
optional-skills/creative/baoyu-article-illustrator/references/workflow.md
ADDED
|
@@ -0,0 +1,332 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Detailed Workflow Procedures
|
| 2 |
+
|
| 3 |
+
## Step 1: Detect Reference Images
|
| 4 |
+
|
| 5 |
+
If the user provides reference images (local path or URL), the goal is to produce **textual descriptions** that can be embedded in prompts — `image_generate` doesn't accept reference-image inputs, and Hermes' text file tools can't read or write binaries.
|
| 6 |
+
|
| 7 |
+
**Tool rules**:
|
| 8 |
+
|
| 9 |
+
| Task | Tool | Notes |
|
| 10 |
+
|------|------|-------|
|
| 11 |
+
| Analyze a reference image | `vision_analyze` | Accepts URL or local path. Ask for style, palette, composition, subject. |
|
| 12 |
+
| Write the text description | `write_file` | Sidecar `.md` files only — never try to `write_file` a PNG/JPG. |
|
| 13 |
+
| (Optional) Keep a local copy of the binary | `terminal` | `cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"` — purely for the record; the skill itself doesn't read the binary. |
|
| 14 |
+
|
| 15 |
+
| Input Type | Action |
|
| 16 |
+
|------------|--------|
|
| 17 |
+
| Image file path provided | `vision_analyze` → write sidecar `.md`. Optional `terminal cp` for a local record. |
|
| 18 |
+
| Image URL provided | `vision_analyze` with the URL → write sidecar `.md`. |
|
| 19 |
+
| Image in conversation (no path, no URL) | Ask via `clarify` for a path or URL, or for a verbal description. |
|
| 20 |
+
| User can't provide either | Extract style/palette verbally from the user → write `references/extracted-style.md`. Do NOT add `references:` to prompt frontmatter. |
|
| 21 |
+
|
| 22 |
+
**Procedure** (when a path/URL is available):
|
| 23 |
+
|
| 24 |
+
1. Call `vision_analyze(image_url=..., question="Describe the style, color palette (with hex approximations), composition, and subject so this can be used as a style/palette reference for another illustration.")`.
|
| 25 |
+
2. Write `{output-dir}/references/NN-ref-{slug}.md` via `write_file` with the description.
|
| 26 |
+
3. (Optional) Run `terminal` with `cp` (or `curl -sSL -o ...` for URLs) to keep a local binary copy. Not required by the skill.
|
| 27 |
+
4. Mark the reference in the outline with usage `direct` / `style` / `palette`. In Step 5.1 the description gets appended to the prompt body.
|
| 28 |
+
|
| 29 |
+
**Sidecar File Format**:
|
| 30 |
+
```yaml
|
| 31 |
+
---
|
| 32 |
+
ref_id: NN
|
| 33 |
+
source: "<original path or URL>"
|
| 34 |
+
local_copy: "NN-ref-{slug}.png" # omit if no copy made
|
| 35 |
+
usage_hint: style # direct | style | palette
|
| 36 |
+
---
|
| 37 |
+
[vision_analyze description — colors, style, composition, subject]
|
| 38 |
+
```
|
| 39 |
+
|
| 40 |
+
---
|
| 41 |
+
|
| 42 |
+
## Step 2: Analyze
|
| 43 |
+
|
| 44 |
+
### 2.1 Determine Output Directory
|
| 45 |
+
|
| 46 |
+
| Input | Output Directory | Source-save path |
|
| 47 |
+
|-------|------------------|------------------|
|
| 48 |
+
| Article file path | `{article-dir}/imgs/` (default) | — (read article via `read_file`) |
|
| 49 |
+
| Pasted content | `illustrations/{topic-slug}/` (cwd) | `source-{slug}.{ext}` (save via `write_file`) |
|
| 50 |
+
|
| 51 |
+
If the user explicitly asked for a different layout (e.g., images in the article's folder, or an `illustrations/` subdirectory), honor that.
|
| 52 |
+
|
| 53 |
+
### 2.2 Analyze Content
|
| 54 |
+
|
| 55 |
+
| Analysis | Description |
|
| 56 |
+
|----------|-------------|
|
| 57 |
+
| Content type | Technical / Tutorial / Methodology / Narrative |
|
| 58 |
+
| Illustration purpose | information / visualization / imagination |
|
| 59 |
+
| Core arguments | 2-5 main points to visualize |
|
| 60 |
+
| Visual opportunities | Positions where illustrations add value |
|
| 61 |
+
| Recommended type | Based on content signals and purpose |
|
| 62 |
+
| Recommended density | Based on length and complexity |
|
| 63 |
+
|
| 64 |
+
Save analysis to `{output-dir}/analysis.md` using `write_file`.
|
| 65 |
+
|
| 66 |
+
### 2.3 Extract Core Arguments
|
| 67 |
+
|
| 68 |
+
- Main thesis
|
| 69 |
+
- Key concepts reader needs
|
| 70 |
+
- Comparisons/contrasts
|
| 71 |
+
- Framework/model proposed
|
| 72 |
+
|
| 73 |
+
**CRITICAL**: If the article uses metaphors (e.g., "电锯切西瓜"), do NOT illustrate literally. Visualize the **underlying concept**.
|
| 74 |
+
|
| 75 |
+
### 2.4 Identify Positions
|
| 76 |
+
|
| 77 |
+
**Illustrate**:
|
| 78 |
+
- Core arguments (REQUIRED)
|
| 79 |
+
- Abstract concepts
|
| 80 |
+
- Data comparisons
|
| 81 |
+
- Processes, workflows
|
| 82 |
+
|
| 83 |
+
**Do NOT Illustrate**:
|
| 84 |
+
- Metaphors literally
|
| 85 |
+
- Decorative scenes
|
| 86 |
+
- Generic illustrations
|
| 87 |
+
|
| 88 |
+
### 2.5 Plan Reference Image Usage (if analyzed in Step 1)
|
| 89 |
+
|
| 90 |
+
For each reference image (use the `vision_analyze` description from Step 1):
|
| 91 |
+
|
| 92 |
+
| Analysis | Description |
|
| 93 |
+
|----------|-------------|
|
| 94 |
+
| Visual characteristics | Style, colors, composition |
|
| 95 |
+
| Content/subject | What the reference depicts |
|
| 96 |
+
| Suitable positions | Which sections match this reference |
|
| 97 |
+
| Style match | Which illustration types/styles align |
|
| 98 |
+
| Usage recommendation | `direct` / `style` / `palette` |
|
| 99 |
+
|
| 100 |
+
| Usage | When to Use | How it's applied in Step 5.1 |
|
| 101 |
+
|-------|-------------|------------------------------|
|
| 102 |
+
| `direct` | Reference matches desired output closely | Paste the description (composition + subject + style + palette) into the prompt body |
|
| 103 |
+
| `style` | Extract visual style characteristics only | Append style traits to prompt body |
|
| 104 |
+
| `palette` | Extract color scheme only | Append extracted hex colors to prompt body |
|
| 105 |
+
|
| 106 |
+
Note: `image_generate` does not accept reference-image inputs under any usage type. Everything is mediated through the `vision_analyze` description.
|
| 107 |
+
|
| 108 |
+
---
|
| 109 |
+
|
| 110 |
+
## Step 3: Confirm Settings
|
| 111 |
+
|
| 112 |
+
Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question the user already answered in their request.
|
| 113 |
+
|
| 114 |
+
### Q1: Preset or Type (highest priority)
|
| 115 |
+
|
| 116 |
+
Based on Step 2 content analysis, recommend a preset first (sets both type & style). Look up [style-presets.md](style-presets.md) "Content Type → Preset Recommendations" table.
|
| 117 |
+
|
| 118 |
+
- [Recommended preset] — [brief: type + style + why]
|
| 119 |
+
- [Alternative preset] — [brief]
|
| 120 |
+
- Or choose type manually: infographic / scene / flowchart / comparison / framework / timeline / mixed
|
| 121 |
+
|
| 122 |
+
**If user picks a preset → skip Q3** (type & style both resolved).
|
| 123 |
+
**If user picks a type → Q3 is required.**
|
| 124 |
+
|
| 125 |
+
### Q2: Density
|
| 126 |
+
|
| 127 |
+
- minimal (1-2) — Core concepts only
|
| 128 |
+
- balanced (3-5) — Major sections
|
| 129 |
+
- per-section — At least 1 per section/chapter (Recommended)
|
| 130 |
+
- rich (6+) — Comprehensive coverage
|
| 131 |
+
|
| 132 |
+
### Q3: Style (skip if preset chosen in Q1)
|
| 133 |
+
|
| 134 |
+
Present Core Styles first:
|
| 135 |
+
|
| 136 |
+
- [Best compatible core style] (Recommended)
|
| 137 |
+
- [Other compatible core style 1]
|
| 138 |
+
- [Other compatible core style 2]
|
| 139 |
+
- Other (see full Style Gallery)
|
| 140 |
+
|
| 141 |
+
**Core Styles** (simplified selection):
|
| 142 |
+
|
| 143 |
+
| Core Style | Maps To | Best For |
|
| 144 |
+
|------------|---------|----------|
|
| 145 |
+
| `minimal-flat` | notion | General, knowledge sharing, SaaS |
|
| 146 |
+
| `sci-fi` | blueprint | AI, frontier tech, system design |
|
| 147 |
+
| `hand-drawn` | sketch/warm | Relaxed, reflective, casual |
|
| 148 |
+
| `editorial` | editorial | Processes, data, journalism |
|
| 149 |
+
| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
|
| 150 |
+
| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
|
| 151 |
+
|
| 152 |
+
Style selection based on Type × Style compatibility matrix ([styles.md](styles.md)).
|
| 153 |
+
**In Step 5**, read `styles/<style>.md` for visual elements and rendering rules.
|
| 154 |
+
|
| 155 |
+
### Q4: Palette (optional)
|
| 156 |
+
|
| 157 |
+
If the preset did not specify a palette, offer:
|
| 158 |
+
|
| 159 |
+
- Default (use style's built-in colors) (Recommended)
|
| 160 |
+
- `macaron` — soft pastel blocks on warm cream
|
| 161 |
+
- `warm` — warm earth tones, no cool colors
|
| 162 |
+
- `neon` — vibrant neon on dark backgrounds
|
| 163 |
+
|
| 164 |
+
**Skip if**: preset already resolved palette, or user specified a palette in the request.
|
| 165 |
+
|
| 166 |
+
See Palette Gallery in [styles.md](styles.md#palette-gallery) and full specs in `palettes/<palette>.md`.
|
| 167 |
+
|
| 168 |
+
### Q5: Image Text Language (only when ambiguous)
|
| 169 |
+
|
| 170 |
+
If the article language is different from the user's conversational language, ask which to use:
|
| 171 |
+
- Article language (match article content) (Recommended)
|
| 172 |
+
- User's conversational language
|
| 173 |
+
|
| 174 |
+
**Skip if**: languages match, or the user already specified in the request.
|
| 175 |
+
|
| 176 |
+
### Display Reference Usage (if references saved in Step 1)
|
| 177 |
+
|
| 178 |
+
When presenting the outline preview to the user, show reference assignments:
|
| 179 |
+
|
| 180 |
+
```
|
| 181 |
+
Reference Images:
|
| 182 |
+
| Ref | Filename | Recommended Usage |
|
| 183 |
+
|-----|----------|-------------------|
|
| 184 |
+
| 01 | 01-ref-diagram.png | direct → Illustration 1, 3 |
|
| 185 |
+
| 02 | 02-ref-chart.png | palette → Illustration 2 |
|
| 186 |
+
```
|
| 187 |
+
|
| 188 |
+
---
|
| 189 |
+
|
| 190 |
+
## Step 4: Generate Outline
|
| 191 |
+
|
| 192 |
+
Save as `{output-dir}/outline.md` using `write_file`:
|
| 193 |
+
|
| 194 |
+
```yaml
|
| 195 |
+
---
|
| 196 |
+
type: infographic
|
| 197 |
+
density: balanced
|
| 198 |
+
style: blueprint
|
| 199 |
+
image_count: 4
|
| 200 |
+
references: # Only if references provided
|
| 201 |
+
- ref_id: 01
|
| 202 |
+
filename: 01-ref-diagram.png
|
| 203 |
+
description: "Technical diagram showing system architecture"
|
| 204 |
+
- ref_id: 02
|
| 205 |
+
filename: 02-ref-chart.png
|
| 206 |
+
description: "Color chart with brand palette"
|
| 207 |
+
---
|
| 208 |
+
|
| 209 |
+
## Illustration 1
|
| 210 |
+
|
| 211 |
+
**Position**: [section] / [paragraph]
|
| 212 |
+
**Purpose**: [why this helps]
|
| 213 |
+
**Visual Content**: [what to show]
|
| 214 |
+
**Type Application**: [how type applies]
|
| 215 |
+
**References**: [01] # Optional: list ref_ids used
|
| 216 |
+
**Reference Usage**: direct # direct | style | palette
|
| 217 |
+
**Filename**: 01-infographic-concept-name.png
|
| 218 |
+
|
| 219 |
+
## Illustration 2
|
| 220 |
+
...
|
| 221 |
+
```
|
| 222 |
+
|
| 223 |
+
**Backup rule**: If `outline.md` exists, rename to `outline-backup-YYYYMMDD-HHMMSS.md` before writing.
|
| 224 |
+
|
| 225 |
+
**Requirements**:
|
| 226 |
+
- Each position justified by content needs
|
| 227 |
+
- Type applied consistently
|
| 228 |
+
- Style reflected in descriptions
|
| 229 |
+
- Count matches density
|
| 230 |
+
- References assigned based on Step 2.5 analysis
|
| 231 |
+
|
| 232 |
+
---
|
| 233 |
+
|
| 234 |
+
## Step 5: Generate Prompts
|
| 235 |
+
|
| 236 |
+
**BLOCKING**: Every illustration must have a saved prompt file before any image is generated.
|
| 237 |
+
|
| 238 |
+
For each illustration in the outline:
|
| 239 |
+
|
| 240 |
+
1. **Create prompt file**: `{output-dir}/prompts/NN-{type}-{slug}.md` via `write_file`
|
| 241 |
+
2. **Include YAML frontmatter**:
|
| 242 |
+
```yaml
|
| 243 |
+
---
|
| 244 |
+
illustration_id: 01
|
| 245 |
+
type: infographic
|
| 246 |
+
style: custom-flat-vector
|
| 247 |
+
---
|
| 248 |
+
```
|
| 249 |
+
3. **Load style specs**: Read `styles/<style>.md` (via `read_file`) for visual elements, style rules, and rendering instructions
|
| 250 |
+
4. **Load palette specs** (if palette specified): Read `palettes/<palette>.md` for colors and background. Palette colors **replace** the style's default Color Palette. If no palette specified, use the style's built-in colors.
|
| 251 |
+
5. **Follow type-specific template** from [prompt-construction.md](prompt-construction.md), using rendering from style + colors from palette (or style default)
|
| 252 |
+
6. **Prompt quality requirements** (all REQUIRED):
|
| 253 |
+
- `Layout`: Describe overall composition (grid / radial / hierarchical / left-right / top-down)
|
| 254 |
+
- `ZONES`: Describe each visual area with specific content, not vague descriptions
|
| 255 |
+
- `LABELS`: Use **actual numbers, terms, metrics, quotes from the article** — NOT generic placeholders
|
| 256 |
+
- `COLORS`: Specify hex codes from palette (or style default) with semantic meaning
|
| 257 |
+
- `STYLE`: Describe line treatment, texture, mood, character rendering per style rules
|
| 258 |
+
- `ASPECT`: Specify ratio (e.g., `16:9`)
|
| 259 |
+
7. **Apply defaults**: composition requirements, character rendering, text guidelines
|
| 260 |
+
8. **Backup rule**: If a prompt file exists, rename to `prompts/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
|
| 261 |
+
|
| 262 |
+
**CRITICAL - References in Frontmatter**:
|
| 263 |
+
- Only add `references` field if a sidecar `.md` description exists in `{output-dir}/references/`
|
| 264 |
+
- If style/palette was extracted verbally (no description file), append info to prompt BODY only
|
| 265 |
+
- Before writing frontmatter, confirm the sidecar exists (try `read_file` on the `.md`)
|
| 266 |
+
|
| 267 |
+
### 5.1 Process References (if analyzed in Step 1)
|
| 268 |
+
|
| 269 |
+
Read the `vision_analyze` description from the sidecar `references/NN-ref-{slug}.md` (via `read_file`) and embed it in the prompt body. `image_generate` never receives the binary.
|
| 270 |
+
|
| 271 |
+
| Usage | Action |
|
| 272 |
+
|-------|--------|
|
| 273 |
+
| `direct` | Paste the full reference description (composition, subject, style, palette) into the prompt body |
|
| 274 |
+
| `style` | Append only the style traits: "Style: clean lines, gradient backgrounds..." |
|
| 275 |
+
| `palette` | Append only the hex colors: "Colors: #E8756D coral, #7ECFC0 mint..." |
|
| 276 |
+
|
| 277 |
+
---
|
| 278 |
+
|
| 279 |
+
## Step 6: Generate Images
|
| 280 |
+
|
| 281 |
+
`image_generate` returns a JSON blob with a URL (`{"success": true, "image": "<url>"}`). It does NOT save a local file, does NOT accept an output path, and does NOT let the agent pick a backend/model. Treat the URL as a temporary artifact and download it explicitly.
|
| 282 |
+
|
| 283 |
+
For each prompt file:
|
| 284 |
+
|
| 285 |
+
1. Read the prompt file (via `read_file`) and extract the assembled prompt
|
| 286 |
+
2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
|
| 287 |
+
3. Call `image_generate(prompt=<assembled>, aspect_ratio=<enum>)` and extract the `image` URL from the returned JSON.
|
| 288 |
+
4. **Backup rule**: If `{output-dir}/NN-{type}-{slug}.png` already exists, rename it via `terminal` (`mv "{output-dir}/NN-{type}-{slug}.png" "{output-dir}/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.png"`) before writing.
|
| 289 |
+
5. Download the URL via `terminal`:
|
| 290 |
+
```bash
|
| 291 |
+
curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{image_url}"
|
| 292 |
+
```
|
| 293 |
+
If `curl` is unavailable, fall back to `wget -qO "{output-dir}/NN-{type}-{slug}.png" "{image_url}"`.
|
| 294 |
+
6. Verify the file exists and has non-zero size (`terminal`: `test -s "{path}" && echo ok`).
|
| 295 |
+
7. On generation failure, retry `image_generate` once. On download failure, retry `curl` once with a longer timeout. Then log and continue.
|
| 296 |
+
8. After each generation, report "Generated X/N".
|
| 297 |
+
|
| 298 |
+
---
|
| 299 |
+
|
| 300 |
+
## Step 7: Finalize
|
| 301 |
+
|
| 302 |
+
### 7.1 Update Article
|
| 303 |
+
|
| 304 |
+
Insert after the corresponding paragraph, using the path relative to the article file:
|
| 305 |
+
|
| 306 |
+
| Input | Insert Path |
|
| 307 |
+
|-------|-------------|
|
| 308 |
+
| Article file path (default `imgs-subdir`) | `` |
|
| 309 |
+
| Article file path (images alongside) | `` |
|
| 310 |
+
| Article file path (`illustrations/` subdirectory) | `` |
|
| 311 |
+
| Pasted content | `` (relative to cwd) |
|
| 312 |
+
|
| 313 |
+
Alt text: concise description in the article's language.
|
| 314 |
+
|
| 315 |
+
### 7.2 Output Summary
|
| 316 |
+
|
| 317 |
+
```
|
| 318 |
+
Article Illustration Complete!
|
| 319 |
+
|
| 320 |
+
Article: [path]
|
| 321 |
+
Type: [type] | Density: [level] | Style: [style]
|
| 322 |
+
Location: [directory]
|
| 323 |
+
Images: X/N generated
|
| 324 |
+
|
| 325 |
+
Positions:
|
| 326 |
+
- 01-xxx.png → After "[Section]"
|
| 327 |
+
- 02-yyy.png → After "[Section]"
|
| 328 |
+
|
| 329 |
+
[If failures]
|
| 330 |
+
Failed:
|
| 331 |
+
- NN-zzz.png: [reason]
|
| 332 |
+
```
|