 Motor · moments held still · 90 s |
 The Mail Train · a linocut journey · 25 s |
 İlk Tik · a watch ad · 50 s |
 Atlama Programı · a homage in miniature · 50 s |
 Boş Koltuk · a film set that builds itself · 80 s |
 Yüz Köpek · a data documentary · 90 s |
 Titanik, Son Saatler · a documentary · 5 min |
 cinecode · a pop-art promo · 60 s |
 Fener · an animated tale · 60 s |
 Gökyüzü neden mavi? · an explainer · 45 s, 9:16 |
 Kuzguncuk Fırın · a bakery ad · 15 s, 9:16 |
 Tek Kibrit · a graphic short · 63 s, 9:16 |
## How it works
1. **You say the idea.** One sentence is enough; a full brief goes straight to work.
2. **It asks a few questions** (the idea's readings, what the film is made of, length and format, the look, the sound and the music), each with a recommended answer marked ★.
3. **It shows the plan** as text: the beats second by second and a director card you can change line by line. Then two scenes as stills, before the rest is built.
4. **It renders a draft,** checks it (motion from the first frame, loudness, legibility, repeats), shows it to you, and an independent viewer watches it cold. Your notes change only what they touch.
5. **The final:** full size, mastered to −14 LUFS, with the credits for your video description.
## Two modes
The agent asks this first and recommends one for your goal.
| | **Quick mode** | **Film mode** |
|---|---|---|
| In one line | the whole film in one file, a few questions, a low-res draft, 1–2 revisions | the roadmap and the whole script approved first; then production stage by stage with your OK, or straight to the draft; research, layered sound |
| Best for | anything under about a minute, brand and client pieces included; social clips, explainers, ads, pieces up to about 3 minutes; a short film's first draft in minutes, about 3 approvals | longer films with several scenes, research or archive material: documentaries, narrated pieces, festival shorts; about 6–8 approvals stage by stage, about 3 straight through |
| How | a few questions (incl. the medium, voice-over, music and references) → optional research (stills from films that look like yours, plus real shapes where the subject is real) → the plan as text (beats, director card, the reference board) → two scenes as stills for your OK, then the rest → low-res draft → up to 2 revision rounds on drafts → final render | 6 questions → roadmap → script → style frame → animatic → render; stage by stage each with your OK, or straight from the script to the draft |
| Picture | one self-contained `film.html`: scenes as functions of time, Canvas 2D or three.js / WebGL, on-screen text | three.js scenes with eight look presets, per-shot renders |
| Sound | designed from version 1 in the same file (Web Audio, rendered offline): an ambience bed per scene, effects on the picture's cue table, one shared reverb, music from an arrangement table | a designed sound identity with layered beds, foley, hero moments, voice and music |
| Agents | one main chat builds, renders and revises (fast); research in the background, helpers only for the prediction test, the overlap check, narration takes and an independent viewer of each draft | the main chat builds what it holds; helpers take the independent parts in parallel (sound, narration, research, review) and the chapters of a long film |
You can start in Quick mode and move a film to Film mode later: the beats become the roadmap.
## Two purposes
Asked together with the mode: the mode decides how deep the work goes, the purpose decides what kind of film it is. Everything after it (question defaults, references, gates, checks) follows the purpose.
| | **Cinematic film** | **Ad & product** (brand, launch, promo, explainer) |
|---|---|---|
| Aim | a story, mood or art piece that looks filmed, not rendered | a film that belongs to one subject, says whose it is and what to do next |
| Picture | the cinematic pass: shallow focus and lens character, grain, an operator's inertia, and on request (off by default) 180° motion blur on fast moves, film tonality from the kit's own print curve and gate weave; camera moves chosen for each shot | the specificity and competitor test, names on screen as lower thirds, UI hero shots for software, your brand colours and fonts (open fonts from Fontsource; your own brand font stays local), an end card with a call to action |
| Sound | ambience-led, a signature sound, the music your pick | narrator + music by default |
| Delivery | the format you choose | 9:16, 1:1 and 16:9 variants with safe areas |
| Extra | — | optional: your own footage or screen recordings cut from a word-timed transcript (needs Whisper): pause trims, stutter and retake flags you approve, graphics timed to the words |
Details: `references/purpose-cinematic.md`, `references/purpose-ad.md`, `references/footage-edit.md`. Motion, the camera vocabulary, fonts, sound sync, the hook, one action per shot and the checks are shared by both.
## What you get
- **A writing system** for clever, short, on-target scripts (both modes): diverge then converge, a clear turn when the story has one, ending first, show don't tell, a word budget, a banned-cliché list in English and Turkish, a read-aloud and 30% cut pass, a first-time-viewer check.
- **A named camera and transition vocabulary** (`references/camera-moves.md`): moves, focus moves and transitions (dolly in, orbit, dolly zoom, FPV, handheld, speed ramp, rack focus, match cut, whip pan, J-cut…) with what each makes the viewer feel, default duration, speed and easing. Every shot's camera is one line: *"dolly in, 3 s, slow ease-in-out, toward the figure"*. Both engines implement them as pure functions of time (`film.html` 2.5D camera, `starter/camera.mjs` for three.js).
- **Quick mode starter:** `film.html` with a deterministic timeline, a 2.5D camera with depth planes, transitions, a shared cue table for picture and sound, seeded randomness (with a lazy cache for seeded data), text helpers and name labels sized for diacritics, and small Web Audio voices (pad, kick, tick, hit, riser, whoosh, pluck, a soft lead, foley, ambience beds, a shared generated reverb) with an arrangement table that is checked before every render. Clicking it in a browser plays picture and sound together.
- **Film mode interview** of six questions in three short rounds (the direction board is shown between them), and **eight look presets** (cinematic realistic, anime/cel, pastel storybook, claymation, papercut/collage, retro/synthwave/VHS, glossy commercial, hand-made ink), plus a path to a custom look from your own reference images. The same eight families work in Quick mode too (grade, texture, toon shading, drawings on twos).
- **A voice that belongs to the film:** narration never goes out as the raw engine voice. Each film picks how its voice comes through (close, tape, radio, chorus, underwater, machine…), where it stands (a room, a hall, a stone nave, open air) and can carry the film's signature sound inside it; every line lands at the same dialogue level.
- **Like this video, but …:** drop a video you like into `refs/` and say what to change. Its form is measured (cuts and shot lengths, tempo, palette and light, BPM, how the cuts sit on the beat), you change what you want, and the film is made new on that form, never from its frames or music.
- **Your own song:** bring a song or track and the film follows its beat grid: tempo measured on the whole song, the clip cut on a bar line, cuts and hits on bars and beats, one visual per lyric line; the music ducks under narration automatically.
- **Direction board (Film mode):** once you tell your idea, three visual directions are shown in one image, each a style plus stills from two or three real films whose look carries it (FilmGrab, mood only) with its measured palette; the one you pick is measured into the film's light and colour, and the style frame is checked against it.
- **Looks found for each idea:** directions from real cinema (stills from films, cinematographers and photographers, mood only) and a shelf of style recipes as vocabulary (woodcut, ukiyo-e, shadow puppetry, risograph, silent film and more; most of them by LemoLab, see Credits); only the chosen one is read.
- **Designer-grade typography** (`references/typography.md`): licence-clean, Turkish-verified fonts and pairings from independent open foundries and Fontsource; three pairings dealt per film and shown as specimen cards in the film's own look; typography references from Fonts In Use, Art of the Title, Typewolf, Are.na and your own screenshots (Instagram saves included) in `refs/type/`, measured into a type direction; a taste log that learns your picks across films; phone-size legibility, contrast and diacritic checks; optional word-locked talking-head captions.
- **Sound design essentials:** a light sound identity per film, layered beds, tested ffmpeg recipes, a −14 LUFS master.
- **Small, dependency-free tools:** frame capture (also straight to MP4, and the page's soundtrack to WAV), animatic builder, mixer, mastering, quality checks (including a measured hook check, subject action per scene once the camera move is removed, and loudness and harshness per scene), open-licence asset search with a licence log.
## Requirements
- An AI coding agent that can run local tools: **Claude Code** (desktop app, VS Code extension or terminal); **Cursor** or another agent that can run tools (Codex, Antigravity…) works too. The regular chat at claude.ai cannot run tools on your computer; Claude Code can (ffmpeg, Chrome, the scripts).
- Node.js 22+, Python 3.9+, ffmpeg and Google Chrome (or Chromium / Edge); the agent installs what is missing, with your OK. Nothing else, on Windows either: the kit runs in Claude Code's own PowerShell, with no bash; Git is used only to install and update the kit, never to render. If the kit's guard does not run in a Claude Code session, the film's setup says GUARD OFF (the tests run on Windows and Linux on every push, and on macOS before each change; a whole film made on Windows is not tried yet). The hooks need a recent Claude Code (the exec-form hooks and `onFailure`, 2.1.295 or newer); on an older client the guard may not register and the film still runs.
- A GPU that Chrome can use (any recent Mac, or a PC with a working graphics driver).
- Disk space: Quick mode pipes frames straight into the MP4, so a few hundred MB is enough; Film mode needs a few GB per film while rendering.
Missing one of them? Just start: the agent checks the machine first and offers to install what is missing (it asks before installing anything). Nothing else is installed: the scripts use only built-ins, and three.js loads pinned library versions from a CDN.
**Free Turkish voices, if you want one** (the kit installs none of them; narration otherwise uses Gemini TTS with your key, or the system voice as a stand-in):
- [EMA Lightning](https://huggingface.co/canberkkkkkk/ema-lightning) by Canberk Aslan (Apache 2.0): one clear voice, offline on a CPU, about 800 MB with PyTorch. The kit can use it once installed: `python3 tools/tts.py --install ema`, then `--engine ema`.
- [VoxCPM2 Türkçe ses tasarımı](https://github.com/alexturkey/voxcpm2-turkce-ses-tasarimi) (Apache 2.0): design a voice from a description, seven ready narrators (a documentary voice, a deep storyteller, a news anchor); Apple Silicon or an NVIDIA card, about 3.7 GB.
- [Ahenk](https://github.com/ozguradmin/ahenk-turkish-tts) by Özgür Güler: question intonation, emotions and laughter (large model, NVIDIA card) and Ahenk Cep (small, CPU); the weights are CC BY 4.0, so a film that uses them credits Ahenk.
## Install
Open Claude Code (the desktop app's **Code** tab, the VS Code extension or the terminal) and say:
> Install the cinecode skill from https://github.com/sarpstar/cinecode
It fetches the kit from GitHub with git into `~/.claude/skills/cinecode` (Windows: `%USERPROFILE%\.claude\skills\cinecode`); on a Windows computer without git it installs git first (`winget install --id Git.Git -e`), after your OK. Then open a new chat. Later, **"update cinecode"** brings the newest version. Install it in one place only, so the agent does not see two copies.
By hand, the same in one line:
```bash
git clone https://github.com/sarpstar/cinecode.git ~/.claude/skills/cinecode
```
The skill starts on everyday film, animation and ad phrases ("kısa film", "animasyon", "reklam filmi", "ürün videosu", "tanıtım videosu", "make a short film", "product video", "ad").
### 1. Claude desktop app (Code)
Open the Claude desktop app, switch to **Code**, select an empty folder for your film, and type **"I want to make a short film"** (Turkish: **"Kısa film yapmak istiyorum"**).
### 2. VS Code extension (Claude Code)
Install the Claude Code extension, open an empty folder, open the Claude Code panel and type the same sentence.
### 3. Terminal
```bash
mkdir my-film && cd my-film && claude
```
Then type the same sentence.
### 4. Cursor
In Cursor's Agent chat, ask for the same install into `~/.cursor/skills/cinecode`, or:
```bash
git clone https://github.com/sarpstar/cinecode.git ~/.cursor/skills/cinecode
```
Open an empty folder in Cursor, open the Agent chat and type the same sentence. The kit's own checks (`make.py`, `qc.py`) run the same; the guard hooks that stop a few mistakes as they happen (a script asked about before it is shown, a draft not shown, a stop right after an approval) run in Claude Code only.
### 5. Other agents (Codex, Antigravity…)
If you use another agent that can run tools and read skills, tell it:
> Install the cinecode skill from https://github.com/sarpstar/cinecode into your skills folder
The agent knows its own folder. The kit's tools and checks run there too; the guard hooks run only in Claude Code. Users have run it in these agents; Claude Code is the recommended setup.
## Quick start
1. Open an empty folder in your agent (see Install).
2. Write your idea. The idea is the only thing you need; leave the rest out if you are not sure, and the agent asks:
```text
Let's make a film with cinecode: