Skip to content

A toolbox of film styles made in code for Claude Code: 66 ready to use, and your own. Each style is a style prompt plus a demo film made entirely in code by Claude Opus 5.5, with no video model. By Lemomo. · 一套用代码做片的风格工具箱:66 种现成风格,也能做出你自己的

tools/directory.py: build the plugin directory edition on the directory branch

lemomo-ai010cd2cd237d
diff --git a/MAINTAINING.md b/MAINTAINING.md
index 6d40d15..9f4e878 100644
--- a/MAINTAINING.md
+++ b/MAINTAINING.md
@@ -47,3 +47,13 @@ Don't push before the upload has finished, and don't commit `tools/assets.json`
## Revise a style
Back up first (old versions move out of the repository, not into git). Re-render, replace `<slug>.mp4`, and run `sh tools/publish.sh`: it re-uploads the film and refreshes its web cut.
+
+## Directory edition
+
+The Claude plugin directory lists a self-contained build of the plugin, on the orphan branch `directory` (the submission tracks that branch; `main` stays what visitors see). It carries the guides, every `STYLE.md` / `style.json` / `DEMO.md`, `core/` (without the Poly Haven models, which only demo code uses) and its own `README.md`, `SECURITY.md` and `SKILL.md`: nothing is cloned or fetched to tell the agent what to do, there are no demo sources, and Chinese edge-tts narration is used only with the user's consent. The sources of the plugin-only files are in `tools/directory/`; the build and its checks (file sizes, personal info) are in `tools/directory.py`.
+
+After a release on `main` (new styles, changed guides or tools):
+
+1. `git worktree add ../lemo-opuscar-directory directory` (once; reuse it afterwards).
+2. `python3 tools/directory.py <version> --into ../lemo-opuscar-directory`, with the version one above the branch's current `.claude-plugin/plugin.json`. It stops when a guide changed so much that one of its edits no longer applies: update `EDITS` in the script.
+3. `claude plugin validate ../lemo-opuscar-directory`, then commit there (`Lemo-Opuscar <version>, plugin directory edition`) and push `directory`. The directory scans each push and publishes the new version.
diff --git a/tools/directory.py b/tools/directory.py
new file mode 100644
index 0000000..4d3c1df
--- /dev/null
+++ b/tools/directory.py
@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Build the Claude plugin directory edition of Lemo-Opuscar from main.
+
+ python3 tools/directory.py <version> build into .release/directory/
+ python3 tools/directory.py <version> --into <dir> then sync it into <dir> (a worktree of the `directory` branch)
+
+The directory edition is a self-contained plugin: the guides, every STYLE.md / style.json / DEMO.md and the core/
+tools travel inside the plugin, so nothing is cloned or fetched to tell the agent what to do. It leaves out the films,
+the demo sources and the big assets (see MAINTAINING.md, "Directory edition"). Only files tracked by git are copied.
+The text changes below are checked: when a guide changes on main and a replacement no longer matches, the build stops.
+"""
+import hashlib, json, os, re, shutil, subprocess, sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+OUT = os.path.join(ROOT, '.release', 'directory')
+LIB = 'skills/lemo-opuscar/library' # where the bundled library sits inside the plugin
+REPO = 'https://github.com/lemomo-ai/lemo-opuscar'
+GALLERY = 'https://lemomo-ai.github.io/lemo-opuscar/'
+
+# what the library keeps (git pathspecs); core/assets/polyhaven models are only used by demo code, which isn't bundled
+KEEP = ['AGENTS.md', 'DIRECTOR.md', 'TECHNIQUE.md', 'LICENSE', 'package.json', 'package-lock.json',
+ 'requirements.txt', 'requirements-voice.txt', 'requirements-music.txt', 'core', 'tools/fetch.sh',
+ 'tools/assets.json', 'styles/README.md', 'styles/*/STYLE.md', 'styles/*/style.json', 'styles/*/DEMO.md']
+DROP = ['core/assets/polyhaven/desk_lamp_arm_01/', 'core/assets/polyhaven/tea_set_01/', 'styles/_template/']
+
+SETUP_OLD = 'plugin/skills/lemo-opuscar/scripts/setup.sh'
+EDGE_CONSENT = ('it sends the narration text to Microsoft, so in this edition use it only when the user asks for it '
+ 'and agrees to that')
+
+# (file, old, new): exact replacements in the bundled copies, each must match once
+EDITS = [
+ ('AGENTS.md', '| Adding a style to the library (owner only) | [`MAINTAINING.md`](MAINTAINING.md) |\n', ''),
+ ('DIRECTOR.md',
+ 'a good Chinese voice uses Microsoft\'s online service (edge-tts) and needs a connection; offline, Kokoro reads Chinese but sounds plain (TECHNIQUE.md §4).',
+ 'offline, Kokoro reads Chinese but sounds plain; Microsoft\'s online service (edge-tts) sounds much better, but '
+ + EDGE_CONSENT + ' (TECHNIQUE.md §4). Default: Kokoro.'),
+ ('DIRECTOR.md',
+ ' Before delivery, put your contact sheet next to the demo poster (`styles/<slug>/poster.jpg`) as a last check.',
+ ''),
+ ('TECHNIQUE.md',
+ 'Kokoro + model (English, offline), edge-tts (Chinese, online), faster-whisper (voice check)',
+ 'Kokoro + model (English and plain Chinese, offline), edge-tts (better Chinese, online, only with the user\'s consent), faster-whisper (voice check)'),
+ ('TECHNIQUE.md',
+ 'with the same outputs as `tts.py`, a rate per line and the silence trimmed. **It needs a network connection.**',
+ 'with the same outputs as `tts.py`, a rate per line and the silence trimmed. **It needs a network connection, and '
+ + EDGE_CONSENT + '.** Without that, use Kokoro\'s Chinese voices.'),
+ ('TECHNIQUE.md',
+ ' In skill mode, get the source with `sh <skill folder>/scripts/setup.sh demo <slug>`. Copied demo code often reaches the library with `../..`: replace that with `$LIB` or absolute URLs.',
+ ' This edition of the plugin doesn\'t include the demo sources: read `DEMO.md` for how a demo was built and write your own code.'),
+ ('core/README.md', '| find, clone or update the library; prints `LIB=<path>` |',
+ '| run by the skill\'s `scripts/setup.sh`, which copies the bundled library to its working folder; prints `LIB=<path>` |'),
+ ('core/README.md', '| `… setup.sh demo <slug>` | adds one style\'s demo source and poster (to read, not to render) |\n', ''),
+ ('core/README.md', '| edge-tts (Microsoft), online; same outputs as `tts.py`.',
+ '| edge-tts (Microsoft), online: sends the text to Microsoft, use it only with the user\'s consent; same outputs as `tts.py`.'),
+ ('core/README.md', '(default `~/lemo-opuscar`)', '(default `~/.lemo-opuscar`)'),
+]
+
+
+def die(msg):
+ sys.exit(f'✗ {msg}')
+
+
+def tracked():
+ out = subprocess.run(['git', '-C', ROOT, 'ls-files', '-z', '--', *KEEP], capture_output=True, text=True, check=True).stdout
+ return sorted(f for f in out.split('\0') if f and not any(f.startswith(d) for d in DROP))
+
+
+def write(rel, text):
+ path = os.path.join(OUT, rel)
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ with open(path, 'w', encoding='utf-8') as f: f.write(text)
+
+
+def build(version):
+ if not re.fullmatch(r'\d+\.\d+\.\d+', version): die(f'version must look like 1.0.0, not {version!r}')
+ shutil.rmtree(OUT, ignore_errors=True)
+ files = tracked()
+ for f in files:
+ dst = os.path.join(OUT, LIB, f)
+ os.makedirs(os.path.dirname(dst), exist_ok=True)
+ shutil.copy2(os.path.join(ROOT, f), dst)
+ # the library's own setup script replaces the clone-and-update one: every guide points to it
+ shutil.copy2(os.path.join(ROOT, 'tools', 'directory', 'library-setup.sh'), os.path.join(OUT, LIB, 'tools', 'setup.sh'))
+ for dirpath, _, names in os.walk(os.path.join(OUT, LIB)):
+ for n in names:
+ p = os.path.join(dirpath, n)
+ if not n.endswith(('.md', '.txt', '.py', '.sh', '.mjs', '.js')): continue
+ s = open(p, encoding='utf-8').read()
+ if SETUP_OLD in s:
+ open(p, 'w', encoding='utf-8').write(s.replace(SETUP_OLD, 'tools/setup.sh'))
+ for rel, old, new in EDITS:
+ p = os.path.join(OUT, LIB, rel)
+ s = open(p, encoding='utf-8').read()
+ if s.count(old) != 1: die(f'{rel}: the text to replace is gone or not unique (update EDITS in tools/directory.py):\n {old[:120]}')
+ open(p, 'w', encoding='utf-8').write(s.replace(old, new))
+ # plugin files
+ src = os.path.join(ROOT, 'tools', 'directory')
+ styles = sum(1 for f in files if f.endswith('/STYLE.md'))
+ for name, rel in [('SKILL.md', 'skills/lemo-opuscar/SKILL.md'), ('README.md', 'README.md')]:
+ write(rel, open(os.path.join(src, name), encoding='utf-8').read().replace('{STYLES}', str(styles)).replace('{VERSION}', version))
+ os.makedirs(os.path.join(OUT, 'skills/lemo-opuscar/scripts'), exist_ok=True)
+ shutil.copy2(os.path.join(src, 'setup.sh'), os.path.join(OUT, 'skills/lemo-opuscar/scripts/setup.sh'))
+ shutil.copy2(os.path.join(src, 'SECURITY.md'), os.path.join(OUT, 'SECURITY.md'))
+ shutil.copy2(os.path.join(ROOT, 'LICENSE'), os.path.join(OUT, 'LICENSE'))
+ # setup.sh copies the library out again when this stamp changes: the version plus a hash of the library's files
+ h = hashlib.sha256()
+ for d, _, ns in sorted(os.walk(os.path.join(OUT, LIB))):
+ for n in sorted(ns):
+ p = os.path.join(d, n); h.update(os.path.relpath(p, OUT).encode()); h.update(open(p, 'rb').read())
+ write(f'{LIB}/.edition', f'{version}-{h.hexdigest()[:12]}\n')
+ plugin = {
+ 'name': 'lemo-opuscar',
+ 'displayName': 'Lemo-Opuscar',
+ 'version': version,
+ 'description': f'{styles} film styles, each with a short film made entirely in code. Pick a style, bring your own story, '
+ 'and let Claude direct the film. No video model, no stock footage.',
+ 'author': {'name': 'Lemomo', 'url': 'https://github.com/lemomo-ai'},
+ 'homepage': REPO,
+ 'repository': REPO,
+ 'license': 'MIT',
+ }
+ write('.claude-plugin/plugin.json', json.dumps(plugin, indent=2, ensure_ascii=False) + '\n')
+ check()
+ total = sum(os.path.getsize(os.path.join(d, n)) for d, _, ns in os.walk(OUT) for n in ns)
+ count = sum(len(ns) for _, _, ns in os.walk(OUT))
+ print(f'✓ directory edition {version}: {count} files, {total / 2**20:.1f} MiB → {os.path.relpath(OUT, ROOT)}/')
+
+
+def check():
+ """The directory's automatic checks that can be run here, plus our own rule: no personal info."""
+ bad = []
+ # the maintainer's home folder is read here at run time, so no name is written into this file
+ pat = re.compile('|'.join([re.escape(os.path.expanduser('~')), r'[\w.+-]+@gmail\.com', r'/Users/', r'\.DS_Store']))
+ for d, _, ns in os.walk(OUT):
+ for n in ns:
+ p = os.path.join(d, n); rel = os.path.relpath(p, OUT); size = os.path.getsize(p)
+ if n in ('.DS_Store', 'Thumbs.db'): bad.append(f'{rel}: not allowed')
+ if size >= 5 * 2**20: bad.append(f'{rel}: {size / 2**20:.1f} MiB (limit 5 MiB)')
+ if size >= 256 * 2**10 and not n.endswith(('.jpg', '.jpeg', '.png', '.webp', '.svg', '.woff2', '.woff', '.ttf', '.otf')):
+ bad.append(f'{rel}: {size // 1024} KiB, not an image or font (over 256 KiB goes to a reviewer)')
+ if n.endswith(('.md', '.txt', '.py', '.sh', '.mjs', '.js', '.json')) and pat.search(open(p, encoding='utf-8').read()):
+ bad.append(f'{rel}: personal info or a local path')
+ if sum(len(ns) for _, _, ns in os.walk(OUT)) > 512: bad.append('more than 512 files')
+ if bad: die('the directory edition fails a check:\n ' + '\n '.join(bad))
+
+
+def sync(into):
+ if not os.path.isdir(os.path.join(into, '.git')) and not os.path.isfile(os.path.join(into, '.git')):
+ die(f'{into} is not a git worktree (git worktree add <dir> directory)')
+ for name in os.listdir(into):
+ if name == '.git': continue
+ p = os.path.join(into, name)
+ shutil.rmtree(p) if os.path.isdir(p) and not os.path.islink(p) else os.remove(p)
+ shutil.copytree(OUT, into, dirs_exist_ok=True)
+ print(f'✓ synced into {into}: review with git -C <dir> status, then commit')
+
+
+if __name__ == '__main__':
+ args = sys.argv[1:]
+ if not args or args[0].startswith('-'): die('usage: python3 tools/directory.py <version> [--into <worktree of the directory branch>]')
+ build(args[0])
+ if '--into' in args:
+ i = args.index('--into')
+ if i + 1 >= len(args): die('--into needs a folder')
+ sync(os.path.abspath(args[i + 1]))
diff --git a/tools/directory/README.md b/tools/directory/README.md
new file mode 100644
index 0000000..dba150a
--- /dev/null
+++ b/tools/directory/README.md
@@ -0,0 +1,62 @@
+# Lemo-Opuscar
+
+**{STYLES} film styles, each with a short film made entirely in code.**<br>
+{STYLES} 种影片风格,每种都配一支完全用代码做出来的短片。
+
+Pick a style, bring your own story, and let Claude direct the film. Claude writes the treatment, draws every frame in code, writes an original score, mixes the sound and renders a finished MP4. No video model, no stock footage.
+
+This is the plugin directory edition (version {VERSION}): the guides, the {STYLES} style prompts and the rendering tools, without the demo films. **The films, the gallery and the newest styles live in the main repository: [github.com/lemomo-ai/lemo-opuscar](https://github.com/lemomo-ai/lemo-opuscar).** Watch every demo film on the [gallery](https://lemomo-ai.github.io/lemo-opuscar/).
+
+## Try it
+
+Install the plugin from the Claude plugin directory. (The full edition, with the demo sources, installs from the main repository instead: `claude plugin marketplace add lemomo-ai/lemo-opuscar`, then `claude plugin install lemo-opuscar@lemolab`. Use one or the other.)
+
+Open Claude Code in a folder for your film, and ask:
+
+> Make a 45-second watercolor film about my family's coffee farm. Warm female narrator.
+
+> Make a 40-second LiDAR Survey film about the old quarry behind our town, from public laser-scan data.
+
+> Make a 30-second whiteboard explainer about how vaccines train the immune system.
+
+> Which film styles are there? I want something for a product launch.
+
+Name a style in English or Chinese, or describe your topic and let Claude suggest two or three. Claude asks you once, up front: anything about your topic it can't decide, whether you have your own voice, music or photos, and whether you want to see a storyboard first. Then it makes the film in a project folder where you started.
+
+## Before you start
+
+- **Claude Code on your own computer.** The plugin renders video with local tools, so it needs a shell: it does not run in the claude.ai chat.
+- **Node 20+, ffmpeg and Python 3.11+** (or [uv](https://docs.astral.sh/uv/)). You install these; Claude tells you if one is missing.
+- A film takes about 30–60 minutes and a fair amount of tokens. Default output 1920×1080, 24 fps; other sizes on request.
+- The styles are tuned for Claude Opus 5.5; other models may not reproduce them.
+
+## What it downloads
+
+The library ships inside the plugin. On first use it is copied to `~/.lemo-opuscar` (set `LEMO_OPUSCAR_HOME` for another folder), and packages install there, so they survive plugin updates. Nothing is installed system-wide. Claude downloads only what your film needs:
+
+| What | From | When | Size |
+|---|---|---|---|
+| Node packages: `playwright-core`, `three` | npm | first film | ~10 MB |
+| Headless Chromium for frame-by-frame rendering | Playwright's download servers (Microsoft) | first film | ~100–200 MB |
+| Python packages: numpy, scipy, soundfile, soxr, pillow | PyPI | first film | ~150 MB |
+| Voice tier: kokoro-onnx, edge-tts, faster-whisper | PyPI | only for a film with narration | ~200 MB |
+| Kokoro voice model (offline TTS) | this project's [GitHub Releases](https://github.com/lemomo-ai/lemo-opuscar/releases/tag/assets) | only for a film with narration | 354 MB |
+| Whisper model for the speech check | Hugging Face (or the mirror you set in `HF_ENDPOINT`) | first narration check | ~145 MB |
+| numba, for plucked strings | PyPI | only if the score uses them | ~140 MB |
+| Instrument sample libraries (VSCO 2 CE, VCSL, FreePats, Karoryfer, Salamander) | this project's GitHub Releases | only the libraries the score uses | 70–400 MB each |
+| HDRIs for 3D styles (Poly Haven, CC0) | this project's GitHub Releases | only for 3D styles | 12 MB |
+| Fonts named by a style (Google Fonts, OFL) | Google Fonts | when the style needs them | small |
+| Packages a style lists in its `STYLE.md` (e.g. a LiDAR reader) | npm or PyPI, into your project folder | only for that style | varies |
+| Public data for the Evidence Films styles (satellite imagery, laser scans, open city data) | the open-data sources Claude finds for your topic; it tells you each source and licence | only when you ask for such a film | varies |
+
+## Privacy and outside services
+
+- Your topic, your files and the film stay on your computer. The plugin collects nothing and sends nothing to us.
+- **Chinese narration:** offline Kokoro voices by default. Better Chinese voices come from Microsoft's online speech service (edge-tts), which receives the narration text; Claude asks before using it and uses it only if you agree. English narration is always offline (Kokoro).
+- The downloads above request files only; they don't send your content. Every third-party asset in a film (fonts, samples, data) is listed with its licence in the film's `CREDITS`.
+
+## Licence
+
+MIT. Fonts in `core/fonts/` are OFL; the sample libraries and HDRIs keep their own licences (listed in `core/audio/INSTRUMENTS.md` and `core/assets/polyhaven/SOURCES.md`). You are responsible for the material you put in your films.
+
+Made by LemoLab · by Lemomo ([@lemomo_ai](https://x.com/lemomo_ai)). Problems or ideas: [open an issue](https://github.com/lemomo-ai/lemo-opuscar/issues) in the main repository.
diff --git a/tools/directory/SECURITY.md b/tools/directory/SECURITY.md
new file mode 100644
index 0000000..7e7e5d5
--- /dev/null
+++ b/tools/directory/SECURITY.md
@@ -0,0 +1,21 @@
+# Lemo-Opuscar security policy · 安全问题报告
+
+## How to report
+
+Please don't open a public issue for a security problem. Report it privately: on the main repository's **Security** page, click **Report a vulnerability** ([direct link](https://github.com/lemomo-ai/lemo-opuscar/security/advisories/new)). Include the plugin version, what you asked for, and how to reproduce it.
+
+## What counts
+
+- Your files, your topic or your film leaving your computer, other than the narration text sent to Microsoft's speech service after you agreed to Chinese online voices.
+- Something downloaded that the README doesn't list, or from somewhere else.
+- Files written or deleted outside your project folder and the library folder (`~/.lemo-opuscar`), or a way for someone to run commands on your computer through the plugin.
+
+Open a normal issue for films that look wrong and for bugs.
+
+## Supported versions
+
+Only the latest release gets fixes. A fix ships as a new version of the plugin.
+
+## 中文
+
+发现安全问题,请不要开公开 issue,到主仓库的 **Security** 页点 **Report a vulnerability** 私下提交([直达链接](https://github.com/lemomo-ai/lemo-opuscar/security/advisories/new)),写上插件版本、你让它做了什么、怎么复现。片子不好看、功能 bug 照常开 issue。
diff --git a/tools/directory/SKILL.md b/tools/directory/SKILL.md
new file mode 100644
index 0000000..af40aef
--- /dev/null
+++ b/tools/directory/SKILL.md
@@ -0,0 +1,26 @@
+---
+name: lemo-opuscar
+description: Direct and produce a short film made entirely in code, in one of the styles of the Lemo-Opuscar library (e.g. Impasto Oil Painting 油画厚涂, Watercolor Brush 水彩笔刷, Ukiyo-e 浮世绘, Satellite Briefing 卫星简报, Exploded Teardown 产品拆解, Microscope Story 显微叙事). Use when the user asks for a video, film, short, promo, explainer or animation (视频、短片、动画、宣传片) in a named style, including data, science and product explainers built from real material such as satellite imagery, laser scans, CAD files or archive scans (数据解说、科普、产品拆解); when they want a film made about their own topic and haven't chosen a style (help them choose); or when they ask which film styles there are. Not for editing or converting existing video files.
+---
+
+# Lemo-Opuscar
+
+The styles, guides and tools ship with this plugin, in `library/` next to this file. Nothing is downloaded to tell you what to do.
+
+1. **Get the library ready.** Run `sh "<skill base directory>/scripts/setup.sh"`. It copies the bundled library to its working folder (default `~/.lemo-opuscar`, so installed packages survive plugin updates) and prints `LIB=<path>` on its last line.
+2. **Install the core tools early.** Start `sh "<skill base directory>/scripts/setup.sh" deps` right away, in the background if you can: it takes a few minutes the first time. Add `deps voice` or `deps music` later, only if the film needs them (`$LIB/TECHNIQUE.md` §1). Report missing system tools (Node, ffmpeg, Python) in your one round of questions; don't install system software yourself. Packages a style needs (its `STYLE.md` lists them) you install yourself, into the project folder.
+3. **Follow the library.** Read `$LIB/AGENTS.md` and do what it says: finding the style, the one round of questions, the treatment, production and delivery.
+
+What changes in skill mode:
+
+| | |
+|---|---|
+| Project folder | `<name>/` in the folder the user started from (lowercase letters, digits, hyphens; avoid `#` and `?` in the path). Wherever the guides say `films/<name>/`, read this folder |
+| Running tools | from `$LIB`, with the project's absolute path: `cd "$LIB" && node core/render/still.mjs "<project>" 1.5 3`. `sh tools/setup.sh` and `sh tools/fetch.sh` also run from `$LIB` |
+| Library files in pages | absolute URLs: `/core/lib.js`, `/node_modules/three/…` (the project is served at `/@film/`) |
+| Library files in scripts and `build.sh` | `$LIB/…`, with `LIB=<path>` at the top of `build.sh`; never `../..` |
+| Demo films | not in this edition: no `demo/` source and no `poster.jpg`. Each style's `DEMO.md` (how its demo was made) is there; read it only after your `TREATMENT.md` is written, as the guides say. The films are on the gallery, https://lemomo-ai.github.io/lemo-opuscar/, if the user wants to watch one |
+| Chinese narration | Kokoro's Chinese voices (offline) by default. edge-tts (`core/tts/tts_zh.py`) sounds better but sends the narration text to Microsoft's speech service: offer it in your one round of questions and use it only if the user agrees |
+| Big downloads | only what the film needs, from the sources `$LIB/TECHNIQUE.md` §1 lists (npm, PyPI, Playwright's browser, this library's GitHub Releases, Hugging Face for the speech check). Name them in your one round of questions the first time |
+
+Deliver what `$LIB/DIRECTOR.md` §11 lists, in the project folder, and tell the user where it is.
diff --git a/tools/directory/library-setup.sh b/tools/directory/library-setup.sh
new file mode 100644
index 0000000..af97650
--- /dev/null
+++ b/tools/directory/library-setup.sh
@@ -0,0 +1,65 @@
+#!/bin/sh
+# Lemo-Opuscar library (plugin directory edition): check the tools and install packages. Run from anywhere.
+# sh tools/setup.sh report what is missing → prints LIB=<path>
+# sh tools/setup.sh deps [voice] [music] install packages: core = Node packages, headless browser, Python core tier;
+# voice = TTS and speech check (+ the English voice model); music = pluck.py (numba)
+# Everything installs inside this library folder (node_modules/, .venv/, core/tts/); nothing outside it changes.
+set -e
+LIB=$(cd "$(dirname "$0")/.." && pwd -P)
+
+# Installed packages are tracked by content: a marker holds a checksum of the files they came from (and the Python
+# version), so a changed package.json or requirements file triggers a reinstall.
+sig() { cat "$@" 2>/dev/null | cksum | cut -d' ' -f1; }
+pysig() { echo "$(sig "$1")-$("$LIB/.venv/bin/python" -V 2>&1 | cut -d. -f1,2)"; }
+req() { [ "$1" = core ] && echo "$LIB/requirements.txt" || echo "$LIB/requirements-$1.txt"; }
+node_ok() { [ "$(cat "$LIB/node_modules/.lemo-ok" 2>/dev/null)" = "$(sig "$LIB/package.json" "$LIB/package-lock.json")" ]; }
+py_ok() { [ "$(cat "$LIB/.venv/.lemo-$1" 2>/dev/null)" = "$(pysig "$(req "$1")")" ]; }
+# a Python 3.11+ for the venv when uv is absent; kokoro-onnx (voice tier) needs < 3.14, so those come first
+find_py() {
+ for c in python3.12 python3.13 python3.11 python3; do
+ "$c" -c 'import sys; sys.exit(sys.version_info < (3, 11))' 2>/dev/null && { echo "$c"; return 0; }
+ done
+ return 1
+}
+
+case "$1" in
+ deps)
+ shift; tiers=core
+ for t in "$@"; do case $t in voice|music) tiers="$tiers $t" ;; *) echo "usage: sh tools/setup.sh deps [voice] [music]"; exit 1 ;; esac; done
+ cd "$LIB"
+ command -v npm >/dev/null || { echo "✗ npm not found: install Node 20+ first"; exit 1; }
+ if ! node_ok; then
+ cp package-lock.json .package-lock.orig
+ npm install --no-audit --no-fund --loglevel=error
+ mv .package-lock.orig package-lock.json # keep the shipped lock file, so the checksum stays the same
+ sig package.json package-lock.json > node_modules/.lemo-ok
+ fi
+ node node_modules/playwright-core/cli.js install chromium-headless-shell # the renderer's browser (a no-op when present)
+ # a venv whose Python is gone (after a Python upgrade) can't be repaired in place: make it again
+ [ ! -e .venv ] || .venv/bin/python -c pass 2>/dev/null || { echo "! $LIB/.venv is broken; making it again"; rm -rf .venv; }
+ if [ ! -x .venv/bin/python ]; then
+ if command -v uv >/dev/null; then uv venv --quiet --python 3.12 .venv
+ else py=$(find_py) || { echo "✗ Python 3.11+ is needed (or install uv, which fetches it)"; exit 1; }; "$py" -m venv .venv; fi
+ fi
+ for t in $tiers; do
+ py_ok "$t" && continue
+ if command -v uv >/dev/null; then uv pip install --quiet --python .venv/bin/python -r "$(req "$t")"
+ else .venv/bin/python -m pip install --quiet --disable-pip-version-check -r "$(req "$t")"; fi
+ pysig "$(req "$t")" > ".venv/.lemo-$t"
+ done
+ case " $tiers " in *" voice "*) [ -f core/tts/kokoro-v1.0.onnx ] && [ -f core/tts/voices-v1.0.bin ] || sh tools/fetch.sh voice ;; esac
+ ;;
+ "") ;;
+ *) echo "usage: sh tools/setup.sh [deps [voice] [music]]"; exit 1 ;;
+esac
+
+# Tools the pipeline needs (report only; installing them is up to the user)
+miss=""
+if command -v node >/dev/null; then
+ [ "$(node -p 'process.versions.node.split(".")[0]')" -ge 20 ] || miss="$miss node20+(found $(node -v))"
+else miss="$miss node20+"; fi
+command -v ffmpeg >/dev/null || miss="$miss ffmpeg"
+command -v uv >/dev/null || find_py >/dev/null || miss="$miss python3.11+(or uv)"
+[ -n "$miss" ] && echo "! missing:$miss"
+node_ok && py_ok core || echo "! packages not installed yet: run 'sh tools/setup.sh deps' (a few minutes) before the first render"
+echo "LIB=$LIB"
diff --git a/tools/directory/setup.sh b/tools/directory/setup.sh
new file mode 100644
index 0000000..9426652
--- /dev/null
+++ b/tools/directory/setup.sh
@@ -0,0 +1,25 @@
+#!/bin/sh
+# Lemo-Opuscar skill (plugin directory edition): put the bundled library in its working folder, then print its path.
+# sh setup.sh copy the library that ships with this plugin (when it is new or changed) → LIB=<path>
+# sh setup.sh deps [voice] [music]
+# the same, then install packages (see the library's tools/setup.sh)
+# The library ships inside the plugin; nothing is cloned or fetched here. It is copied out because the packages
+# (node_modules/, .venv/) and the models it downloads later should survive plugin updates.
+# LEMO_OPUSCAR_HOME = the working folder (default ~/.lemo-opuscar).
+set -e
+SRC=$(cd "$(dirname "$0")/../library" && pwd -P)
+LIB=${LEMO_OPUSCAR_HOME:-$HOME/.lemo-opuscar}
+case "$LIB" in /*) ;; *) LIB=$(pwd)/$LIB ;; esac
+
+stamp=$(cat "$SRC/.edition" 2>/dev/null || echo unknown)
+if [ "$(cat "$LIB/.edition" 2>/dev/null)" != "$stamp" ]; then
+ if [ -e "$LIB" ] && [ -n "$(ls -A "$LIB" 2>/dev/null)" ] && [ ! -f "$LIB/.edition" ]; then
+ echo "✗ $LIB exists and is not a Lemo-Opuscar library folder. Set LEMO_OPUSCAR_HOME to another folder."; exit 1
+ fi
+ mkdir -p "$LIB"
+ # copy over the old files; packages and downloaded models (node_modules/, .venv/, core/tts/*.onnx…) stay
+ cp -R "$SRC/." "$LIB/"
+ echo "✓ library $stamp ready in $LIB"
+fi
+LIB=$(cd "$LIB" && pwd -P)
+exec sh "$LIB/tools/setup.sh" "$@"