Metadata-Version: 2.5
Name: pengcut-kit
Version: 0.1.0
Summary: Make Thai short films with your AI in a closed sandbox: the Lemo-Opuscar film engine, Thai fonts, sound effects and a Thai text check, with no GitHub needed.
Project-URL: Homepage, https://pengcut.furredco.workers.dev
License-Expression: MIT AND OFL-1.1 AND CC0-1.0
License-File: LICENSE
Keywords: ai-agent,film,fonts,pengcut,sound-effects,thai,video
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# pengcut-kit

Everything an AI needs to build a short film with Thai text when its sandbox cannot reach GitHub or the Pengcut site, only npm or PyPI (claude.ai chat; Claude Code cloud at Trusted). Made for Pengcut users (https://pengcut.furredco.workers.dev): Pengcut plans the clip with you through its MCP tools; this kit lets your machine build it. It holds:

- the **Lemo-Opuscar film engine and style library** (MIT, by LemoLab): every film style of the library (the count is `styles` in `kit.json`), each with its recipe (`opuscar/styles/<id>/STYLE.md`) and its demo source, the fonts and HDRIs its demos load (`opuscar/demo-assets.json`), and the shared render tools;
- **19 Thai font files** (OFL): Sarabun, Kanit, Mali, Noto Sans Thai, Noto Serif Thai, Prompt, IBM Plex Sans Thai, Chakra Petch, Mitr, Itim, Pridi;
- **Pengcut's library pieces**: pictures with real transparency and short animations, with Thai names and tags (`node tools/pieces.mjs find ลูกศร`);
- **the most-used sound effects** (CC0), each with its source record: `node tools/sounds.mjs list` shows what this pack holds and what it lacks;
- **the Thai text check**: it tells you which way of drawing text on this machine puts every Thai vowel and tone mark in place;
- a **starter film** that draws Thai whole on the engine.

## Install

One of these, whichever registry your sandbox reaches:

```bash
npx -y pengcut-kit setup          # npm
pip install pengcut-kit && pengcut-kit setup      # PyPI (python -m pengcut_kit setup also works)
```

`setup` copies the kit to `~/pengcut-kit` (or `--dir`), installs the Thai fonts for this user, finds Chrome, installs the engine's npm packages (from npm) and Python packages (from PyPI), and runs the Thai check. It prints what works and the fix for what does not, and writes `setup.json`. Then, before any render: `. ~/pengcut-kit/kit.env` (sets `PLAYWRIGHT_CHROME` so the engine uses the machine's Chrome; nothing is downloaded from Playwright's servers).

## Thai text: three rules

1. **Run the check first and use only a path that passed.** `node ~/pengcut-kit/thai-check/thai-check.mjs` tries Chrome canvas, Pillow and ffmpeg drawtext with the test line "ที่นี่ก็ได้" and compares each with a reference picture. FAIL means upper vowels or tone marks land out of place on that path (the usual fault: the mai ek tone mark drawn into the sara ii vowel; measured 9 Nov 2026 with ffmpeg 6.1 drawtext, the version in claude.ai chat, and with Pillow without raqm; Chrome canvas and the kit's Pillow with raqm passed). Your own path: render the spec (`--spec` prints it) and pass `--image yours.png`. Look at the `-diff.png` it writes when something fails.
2. **Use the kit's fonts**, never a font without Thai glyphs: in a page `<link rel="stylesheet" href="/core/fonts/thai/thai.css">` then `font-family: 'Kanit'` (families and weights in `opuscar/core/fonts/thai/fonts.json`); by file path for Pillow or ffmpeg.
3. **Animate whole clusters.** A typewriter or per-letter reveal must step by grapheme cluster (`new Intl.Segmenter('th', {granularity: 'grapheme'})`), or a tone mark appears alone on screen.

## Build a film

The engine's guides, in order: `opuscar/AGENTS.md` (workflow), `opuscar/DIRECTOR.md`, `opuscar/TECHNIQUE.md`, `opuscar/core/README.md` (every command). A film is a folder with an `index.html` that follows the page contract (`window.READY`, `window.render(t)`, `window.DUR`, optional `window.EV`, `window.TEXTS`). Start from `starter/thai-title/`, and build the chosen style from its recipe (`opuscar/styles/<id>/STYLE.md`); read the style's demo source for technique. The library keeps its demos' fonts and HDRIs out of git and fetches them from GitHub, which a closed sandbox cannot reach; the kit adds them from their open sources (`opuscar/demo-assets.json` lists each, and any it could not find). A demo that needs a file listed as not found will not open: build that style from its recipe instead. Thai text always uses the kit's Thai fonts. Pictures: `node tools/pieces.mjs find <word>` before drawing anything in code.

```bash
. ~/pengcut-kit/kit.env
E=~/pengcut-kit/opuscar
cp -r ~/pengcut-kit/starter/thai-title ~/film && cd ~/film       # then edit TEXT and the look
node $E/core/render/still.mjs ~/film 1 3 5 --size 1080x1920        # look at stills first
node $E/core/render/video.mjs ~/film --size 1080x1920 --fps 24 --out ~/film/out/video.mp4
node $E/core/render/events.mjs ~/film --size 1080x1920 --out ~/film/events.json
node ~/pengcut-kit/tools/mix.mjs ~/film/events.json ~/film/out/mix.wav
sh $E/core/render/mux.sh ~/film/out/video.mp4 ~/film/out/mix.wav ~/film/out/film.mp4
```

Vertical clips (TikTok, Reels, Shorts): `--size 1080x1920` on every command; the library's demos are 1920x1080, so a demo becomes vertical only through the style's own layout (see `opuscar/MY-STYLES.md`, field `size`).

## Sounds

`node ~/pengcut-kit/tools/sounds.mjs list` · `find door` (Thai works: `find ประตู`) · `path door-1`. In an event list a sound can be an id (`door-2`), a term (`door`: its first file) or a file path. A sound that is not in the pack: ask Pengcut `search_sounds` (the MCP result reaches you even when the sandbox network is closed); make it in code only as the last resort, and tell the user.

## Licences

`NOTICE.md`. Films you make are yours. Showing the library's own demo films or stills needs the credit "LemoLab" with a link to https://github.com/lemomo-ai/lemo-opuscar.
