clayvoyant 0.3.2__tar.gz

clayvoyant-0.3.2/.env.example

@@ -0,0 +1,5 @@
+# Copy this file to .env (in your project folder or where you run sastudio) and add your own keys.
+# .env is ignored by git. Keys are read only when you run a paid generation with --live.
+# Never paste a real key into studio.yaml, an issue, a screenshot or a log.
+SARVAM_API_KEY=
+ELEVENLABS_API_KEY=

clayvoyant-0.3.2/.gitignore

@@ -0,0 +1,70 @@
+# Secrets: never commit
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+*.p12
+*.pfx
+id_rsa*
+id_ed25519*
+.netrc
+credentials*.json
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.uv-cache/
+*.log
+
+# Project state (voice cache, ledger, rigs, renders): local to each project
+.studio/
+**/build/
+*.part
+*.part.*
+
+# Media you render
+*.mp4
+*.mov
+*.mkv
+!docs/media/*.mp4
+*.wav
+!src/sastudio/**/*.wav
+
+# OS / editor
+.DS_Store
+Thumbs.db
+*.swp
+*.tmp
+desktop.ini
+.idea/
+.vscode/
+
+# Local editor and AI-agent settings: they can hold machine paths, permission lists or tokens,
+# and are never part of the project
+.claude/
+CLAUDE.local.md
+.cursor/
+.codex/
+.aider*
+.continue/
+.windsurf/
+.zed/
+.hermes/
+.mcp.json
+
+# clay portraits the examples make for themselves (sastudio clay portraits)
+examples/*/assets/characters/*_clay.png

clayvoyant-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibrahim Sultan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clayvoyant-0.3.2/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.5
+Name: clayvoyant
+Version: 0.3.2
+Summary: Clay stop-motion films, written as plain text: sculpted characters, sets, cameras, voices and subtitles from a YAML project. Made for security awareness; see the scam coming.
+Project-URL: Homepage, https://github.com/xIBBAx/clayvoyant
+Project-URL: Repository, https://github.com/xIBBAx/clayvoyant
+Project-URL: Documentation, https://github.com/xIBBAx/clayvoyant/tree/main/docs
+Project-URL: Changelog, https://github.com/xIBBAx/clayvoyant/blob/main/docs/CHANGELOG.md
+Project-URL: Issues, https://github.com/xIBBAx/clayvoyant/issues
+Project-URL: Security, https://github.com/xIBBAx/clayvoyant/security/policy
+Author-email: Ibrahim Sultan <135457750+xIBBAx@users.noreply.github.com>
+Maintainer-email: Ibrahim Sultan <135457750+xIBBAx@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,elevenlabs,phishing,sarvam,security awareness,security training,subtitles,text-to-speech,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: jsonschema<5,>=4.18
+Requires-Dist: pillow<14,>=13.0
+Requires-Dist: pyyaml<7,>=6.0.1
+Provides-Extra: all
+Requires-Dist: kokoro-onnx>=0.6; extra == 'all'
+Requires-Dist: numpy>=1.26; extra == 'all'
+Requires-Dist: scikit-image>=0.22; extra == 'all'
+Requires-Dist: scipy>=1.11; extra == 'all'
+Provides-Extra: clay
+Requires-Dist: numpy>=1.26; extra == 'clay'
+Requires-Dist: scikit-image>=0.22; extra == 'clay'
+Requires-Dist: scipy>=1.11; extra == 'clay'
+Provides-Extra: voices
+Requires-Dist: kokoro-onnx>=0.6; extra == 'voices'
+Requires-Dist: numpy>=1.26; extra == 'voices'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/xIBBAx/clayvoyant/main/docs/media/brand/mark-clay-512.png" width="168" alt="The project's mark, sculpted in clay by the engine itself: a round teal disc pressed with the ridges of a thumbprint, which circle an orange eye.">
+</p>
+
+<h1 align="center">Clayvoyant</h1>
+
+<p align="center">
+  <b>See the scam coming.</b><br>
+  <b>Clay stop-motion films, written as plain text.</b><br>
+  Describe the people, write what they say, choose where it happens.<br>
+  The studio sculpts the cast, builds the set, lights it, films it and gives it a voice.
+</p>
+
+<p align="center">
+  <a href="#make-a-film">Make a film</a> ·
+  <a href="https://github.com/xIBBAx/clayvoyant/tree/main/examples/the-fast-one/">The sample film</a> ·
+  <a href="https://github.com/xIBBAx/clayvoyant/blob/main/docs/INDIA.md">For India</a> ·
+  <a href="https://github.com/xIBBAx/clayvoyant/blob/main/docs/CLAY_MOTION.md">How the clay works</a> ·
+  <a href="#documentation">Documentation</a> ·
+  <a href="https://github.com/xIBBAx/clayvoyant/blob/main/docs/ROADMAP.md">Roadmap</a>
+</p>
+
+<p align="center">
+  <a href="https://xibbax.github.io/clayvoyant/"><img src="https://raw.githubusercontent.com/xIBBAx/clayvoyant/main/docs/media/film/the-fast-one.gif" width="800" alt="A few seconds of the sample film The Fast One: in a cafe at dusk, Tara, a clay figure with a ponytail and a mustard jacket, sits at a round table with a laptop and talks with Odile, who runs the cafe. Their mouths move with the words, they turn to each other and gesture, and the camera cuts between a two-shot and close-ups."></a><br>
+  <a href="https://xibbax.github.io/clayvoyant/"><b>Watch the whole film</b></a> (82 seconds) ·
+  <a href="https://github.com/xIBBAx/clayvoyant/blob/main/docs/SHOWCASE.md"><b>Before and after, frame by frame</b></a>
+</p>
+
+I built Clayvoyant after making a 29-minute clay film to teach information security at my father's
+workplace ([where it began](https://xibbax.github.io/clayvoyant/#where-clayvoyant-began)). It is
+that work, opened up so anyone can make their own films: every figure is sculpted from
+signed-distance clay and rigged with real hands and a face that acts; every room is built by code;
+every shot is planned like a film and can be changed in a line of YAML. Twelve short
+security-awareness stories come with it, ready to make in your organisation's name, words and
+language.
+
+## Make a film
+
+You need Python 3.11+, FFmpeg and [Blender](https://www.blender.org/download/) 4.2 or newer
+([installing them](https://github.com/xIBBAx/clayvoyant/blob/main/docs/INSTALLATION.md)). A GPU makes it quicker; it is not required.
+
+```bash
+git clone https://github.com/xIBBAx/clayvoyant
+cd clayvoyant
+python3 -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[clay,voices]"
+
+sastudio voices install kokoro                     # a free neural voice, downloaded once (350 MB)
+sastudio film examples/the-fast-one --preset draft
+```
+
+That one command voices thirteen lines, sculpts three people, builds a cafe and an office, films
+seventeen shots on twos and assembles a subtitled film in `examples/the-fast-one/build/`. No
+account and no API key. Edit a line and only the shots it can affect are filmed again.
+(`clayvoyant` works in place of `sastudio`: the project was called Security Awareness Studio until
+November 2026.)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/xIBBAx/clayvoyant/main/docs/media/film/the-fast-one-sheet.jpg" width="100%" alt="Twelve frames from The Fast One. A cafe at dusk with the city in the window: Tara at a table with her laptop and Odile behind the counter, seen whole; Tara listening in close-up while Odile explains which Wi-Fi is hers; Tara reading out what the other network wants; the two of them at the table; Odile in close-up, smiling. A key point card. Then an office in morning light: Tara arriving at Bashir's desk; Bashir, bearded and in glasses, asking what stopped her; Tara explaining with her palms open; Bashir standing to make his point; the two of them as he offers to buy the coffee. A last key point card.">
+</p>
+
+**[Watch The Fast One](https://xibbax.github.io/clayvoyant/)**
+(82 seconds, with subtitles). It is exactly what the command above makes with `--preset preview`:
+seventeen filmed shots at 1280x720 and thirteen voiced lines, in 55 minutes on a laptop GeForce GTX
+1660 Ti. Checked drawing by drawing, nothing in it passes through anything
+([how](https://github.com/xIBBAx/clayvoyant/blob/main/docs/CLAY_MOTION.md#nothing-passes-through-anything)).
+
+Everything in [The Fast One](https://github.com/xIBBAx/clayvoyant/tree/main/examples/the-fast-one/) comes from two scene files and one page of
+character descriptions. Nobody opened Blender, drew anything or recorded a voice.
+
+## What you direct
+
+**People.** A character is a few lines: skin, hair, clothes, build, a face nudged wider or
+sharper, and how they carry themselves. Ten hair styles, eight outfits, beards, glasses, a
+headscarf, a bindi. No two characters share a face, even when described alike.
+
+```yaml
+  - id: bashir
+    name: Bashir
+    look:
+      design:
+        skin: "#8A5A3C"
+        hair: { style: short, color: "#16110F" }
+        outfit: { style: shirt, color: "#7FA3C4" }
+        extras: [glasses, beard]
+        body: { build: broad, height: tall }
+        face: { jaw: 0.5, brows: 0.4 }
+      acting: { energy: 0.8, posture: 0.6 }
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/xIBBAx/clayvoyant/main/docs/media/characters/clay-lineup.jpg" width="100%" alt="Six different clay characters in a row, each made from a short description: a woman with long hair in a rust sweater waving; a bearded man in a green hoodie with his hands on his hips; a woman in a headscarf and a blue kurta, palms together; a tall bald man with a moustache and glasses, arms folded; a woman in a mustard zip jacket giving a thumbs-up; a curly-haired person in a knit vest with a lanyard, hand on chin.">
+</p>
+
+**Performances.** They walk on planted feet, sit down, turn to whoever is speaking, point, shrug,
+fold their arms, type with their hands on the desk, carry a mug, read a phone. Mouths follow the
+sounds of the words; eyes lead and the head follows; listeners react. What nobody wrote is acted
+anyway, and what you write wins:
+
+```yaml
+  - id: fo_04
+    who: odile
+    go: table_left_2                 # walks over and takes the seat
+    emotion: concern
+    act: [hold_mug]
+    reactions: { tara: worried }
+    say: "Then somebody in here is fishing. And not for coffee."
+```
+
+**Places.** Office, reception, meeting room, home, cafe, corridor, street and classroom: built
+by code, dressed in your organisation's colours and name, lit for morning, day, evening or night.
+No model files, no photographs, nothing to license.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/xIBBAx/clayvoyant/main/docs/media/film/sets.jpg" width="100%" alt="The eight sets as establishing shots: an office with desks and a wall of windows, a reception with a branded counter, a meeting room with a wall screen, a home with a sofa and a garden window, a cafe with round tables and pendant lamps, a corridor with wall lights, a street of shop fronts with trees and a bench, and a classroom with rows of desks and a board.">
+</p>
+
+**The camera.** Nine framings, seven moves, seven lighting moods, depth of field. Left alone, the
+planner cuts like an editor: an answer gets a close-up, a question is seen over a shoulder, a long
+line cuts away to the listener between two words, and no scene opens or ends the way the one before
+it did. Every face gets room to look into, and no shot shows the back of a speaker's head.
+`sastudio direct` prints the shot list before anything is filmed.
+
+**Beginnings.** A scene opens on a filmed shot of its place with the title over it, entered the
+way the story asks: a slow push into the room, a door that opens, the camera pulling back from an
+object, a match cut on a face. Never a wipe.
+
+**Voices.** [Kokoro](https://github.com/xIBBAx/clayvoyant/blob/main/docs/VOICE_PROVIDERS.md#kokoro), a free neural voice that runs on your
+computer, in British and American English and Hindi. Or your own recordings, one file per line.
+Or Sarvam and ElevenLabs with your own key, a spending cap and a ledger; nothing paid ever runs
+without `--live`. One film per language from the same project.
+
+**Your own models.** A rigged glTF, FBX or OBJ character can join the cast with
+`sastudio model import`; sculpted characters export to GLB, FBX, OBJ or `.blend`.
+
+## The other renderer
+
+The cards renderer needs no Blender and no GPU: the same scripts as a captioned film of drawn
+characters who talk and blink, in three styles (sketch, flat, paper cut-out), fourteen minutes
+rendered in about a minute.
+
+```bash
+sastudio init my-film --org "Riverside Public School" --email it-help@riverside-school.in --style v3
+sastudio render my-film --preset draft
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/xIBBAx/clayvoyant/main/docs/media/characters/styles.png" width="640" alt="The five bundled characters in four styles, one row each: sketch, flat, paper cut-out and clay.">
+</p>
+
+## For India
+
+Five everyday scams, each a short scene in English and Hindi, in your organisation's name:
+"digital arrest" on a video call, a UPI request that wants your PIN, a caller who needs your OTP,
+an electricity-bill message with an app to install, and a customer-care number from the top of a
+search. Every line of advice follows an advisory from I4C, the RBI or the Department of
+Telecommunications, and each scene names its source.
+
+```bash
+sastudio init my-film --template india --org "Sunrise Senior Citizens Forum" --email help@sunrise-forum.org
+sastudio film my-film --preset draft --lang hi-IN
+```
+
+`sastudio posters my-film` prints each scene's lesson as an A4 poster, for a notice board.
+`sastudio share my-film --each` makes one upright phone clip per scam, about a minute and 5 MB
+each: small enough to forward. `--lang hi-Latn` gives the Hindi film with its words in Roman
+letters, the way people type Hindi on a phone ("Papa, ek minute ke liye phone neeche rakhiye").
+
+[Films for India](https://github.com/xIBBAx/clayvoyant/blob/main/docs/INDIA.md) has the sources, nine more Indian languages and a checklist for
+showing a film. [Nineteen Thirty](https://github.com/xIBBAx/clayvoyant/tree/main/examples/nineteen-thirty/) is the first scene on its own, filmed
+in clay.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["studio.yaml<br/>scenes/*.yaml"] --> B["validate"]
+    B --> C["voices<br/>Kokoro / recorded /<br/>Sarvam / ElevenLabs"]
+    B --> D["direction<br/>shots, light, acting"]
+    B --> E["sculpt<br/>SDF clay, marching cubes"]
+    C --> F["timeline<br/>frame-exact"]
+    D --> G["film<br/>Blender, on twos"]
+    E --> G
+    F --> G
+    G --> H["film.mp4<br/>.srt .vtt<br/>transcript, manifest"]
+```
+
+Acting is a pure function of the frame, so any shot can be filmed alone, shots of one scene always
+agree, and a shot that stopped half way resumes at its first missing drawing. Sculpts, voices and
+shots are cached by content. [ARCHITECTURE.md](https://github.com/xIBBAx/clayvoyant/blob/main/docs/ARCHITECTURE.md) and
+[CLAY_MOTION.md](https://github.com/xIBBAx/clayvoyant/blob/main/docs/CLAY_MOTION.md) have the detail.
+
+## What it costs to run
+
+Measured on one laptop on 2026-11-11 (Intel Core i7-10750H, 12 threads, GeForce GTX 1660 Ti with
+6 GB, Blender 5.2.2 under WSL2):
+
+- Sculpting the sample's three characters: 46 seconds for all three, once per look.
+- Voicing its thirteen lines with Kokoro on the CPU: 26 seconds for 47 seconds of speech.
+- Filming at `preview` (1280x720): 4.7 seconds a drawing, about 2.3 minutes of work for each
+  second of film on twos. `draft` (960x540) takes about half that. People the camera cannot see are
+  not drawn.
+- The cards renderer: the 14-minute starter film in 90 seconds at `preview` and 2 minutes 41 seconds
+  at `final`, on the CPU.
+
+## Known limits
+
+- Kokoro has no Indian-English accent; English lines are read in a British or American voice.
+- Imported models stand, walk, turn, look, talk and gesture; they do not sit or use hands.
+- Lip sync follows the voice's phoneme timings when the provider reports them (Kokoro does), and
+  otherwise the spelling and the loudness of the voice.
+- There is no sound-effect or music library yet: a film has its dialogue and, if you add one, a
+  music track. Rendering on a remote GPU is not built.
+- Another language is another film: you write each line's translation in the scene file and
+  render once per language. Nothing translates for you.
+- The `final` preset (1920x1080) has not yet been run for a whole film; the sample was built with
+  `preview`. CI has no Blender, so the clay smoke test runs only where Blender is installed.
+- The starter scenes are general guidance, not policy. Replace each procedure with your own.
+- On the sofa of the home set, a seated character still sinks into the cushion; Nineteen Thirty
+  shows it ([#28](https://github.com/xIBBAx/clayvoyant/issues/28)).
+- The `india` template's Hindi has not yet been reviewed by fluent speakers from its audience
+  ([#20](https://github.com/xIBBAx/clayvoyant/issues/20)). Read every line aloud with someone who
+  will watch it before you show it.
+
+## Documentation
+
+| Guide | |
+|---|---|
+| [Quickstart](https://github.com/xIBBAx/clayvoyant/blob/main/docs/QUICKSTART.md) | a first film in ten minutes |
+| [Why it exists](https://github.com/xIBBAx/clayvoyant/blob/main/docs/WHY.md) | who it is for, what it costs, how it compares |
+| [Films for India](https://github.com/xIBBAx/clayvoyant/blob/main/docs/INDIA.md) | the `india` template, its sources, Indian languages |
+| [Writing with an assistant](https://github.com/xIBBAx/clayvoyant/blob/main/docs/WRITING_WITH_AN_ASSISTANT.md) | `sastudio brief`: a script from any chat assistant |
+| [Installation](https://github.com/xIBBAx/clayvoyant/blob/main/docs/INSTALLATION.md) and [requirements](https://github.com/xIBBAx/clayvoyant/blob/main/docs/REQUIREMENTS.md) | Ubuntu, WSL2, Windows, Blender, GPUs |
+| [Clay films](https://github.com/xIBBAx/clayvoyant/blob/main/docs/CLAY_MOTION.md) | the engine: sculpting, acting, sets, light, caching |
+| [Characters](https://github.com/xIBBAx/clayvoyant/blob/main/docs/CHARACTERS.md) | describing people; every choice and slider |
+| [Direction](https://github.com/xIBBAx/clayvoyant/blob/main/docs/DIRECTION.md) | sets, marks, cameras, light, gestures, openings |
+| [Scenes](https://github.com/xIBBAx/clayvoyant/blob/main/docs/SCENES.md) and [configuration](https://github.com/xIBBAx/clayvoyant/blob/main/docs/CONFIGURATION.md) | writing scenes, tokens, translations |
+| [Voice providers](https://github.com/xIBBAx/clayvoyant/blob/main/docs/VOICE_PROVIDERS.md) and [API keys](https://github.com/xIBBAx/clayvoyant/blob/main/docs/API_SETUP.md) | Kokoro, recordings, Sarvam, ElevenLabs |
+| [Rendering](https://github.com/xIBBAx/clayvoyant/blob/main/docs/RENDERING.md) | presets, outputs, subtitles, incremental builds |
+| [Architecture](https://github.com/xIBBAx/clayvoyant/blob/main/docs/ARCHITECTURE.md) and [glossary](https://github.com/xIBBAx/clayvoyant/blob/main/docs/GLOSSARY.md) | how it fits together |
+| [Troubleshooting](https://github.com/xIBBAx/clayvoyant/blob/main/docs/TROUBLESHOOTING.md) | common errors and their fixes |
+| [Roadmap](https://github.com/xIBBAx/clayvoyant/blob/main/docs/ROADMAP.md) and [testing](https://github.com/xIBBAx/clayvoyant/blob/main/docs/TESTING.md) | what comes next; how it is checked |
+
+## Responsible use
+
+Never clone a real person's voice or use their likeness without written consent. A film does not
+make an organisation compliant with any standard. Models, sounds and images you bring must be
+yours to use; the studio records the licence you give for each imported model.
+
+## Contributing
+
+Sets, garments, hair, gestures, scene templates, translations, voice adapters, fixes and
+documentation are welcome. [CONTRIBUTING.md](https://github.com/xIBBAx/clayvoyant/blob/main/.github/CONTRIBUTING.md) explains how changes are tested and
+how secrets and unlicensed material are kept out. Please follow the
+[code of conduct](https://github.com/xIBBAx/clayvoyant/blob/main/.github/CODE_OF_CONDUCT.md) and report vulnerabilities privately ([SECURITY.md](https://github.com/xIBBAx/clayvoyant/blob/main/SECURITY.md)).
+Working with a coding assistant? [AGENTS.md](https://github.com/xIBBAx/clayvoyant/blob/main/AGENTS.md) tells it how to make a film here and what
+never to do.
+
+## License
+
+Code, sculpts, sets and sample scripts: [MIT](https://github.com/xIBBAx/clayvoyant/blob/main/LICENSE). Bundled fonts: SIL Open Font License.
+Every bundled file is listed in [ASSET_LICENSES.md](https://github.com/xIBBAx/clayvoyant/blob/main/docs/ASSET_LICENSES.md). Optional voice software
+keeps its own licences ([details](https://github.com/xIBBAx/clayvoyant/blob/main/docs/VOICE_PROVIDERS.md#kokoro)). Films you make are yours, and
+you do not need to credit this project in them.