# zy-cinematic-realism compiles one scene into four model prompts

> A prompt workflow for ChatGPT and Codex that locks the visual design once and then translates it into whatever language a target image model understands, with a decoder that reads a reference image as a set of transferable rules rather than a bag of adjectives. It writes prompts; it does not call an API.

**popopo-99/zy-cinematic-realism** — Turn simple scene ideas into restrained, physically believable cinematic AIGC prompts.

- Repository: https://github.com/popopo-99/zy-cinematic-realism
- Stars: 544 · Forks: 49
- Language: Python
- License: NOASSERTION
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/popopo-99-zy-cinematic-realism

## Scene Master is the only source of truth

Version 2.0 changed the shape of the workflow, and the difference is easy to state.

The old pipeline was an idea, then a skill, then a final prompt. The new one is an idea, then a Scene Master, then a Creative Grammar, then a Model Compiler, and only then one of four named target models.

The Scene Master is the single source of truth. It locks the visual design first: the characters, the story moment, the action, the scene, the camera position, the composition, the light, the props, the time and the weather. Creative Grammar then decides style, photography and staging. The compilers translate.

What a compiler may change is stated explicitly, and it is a short list: syntax, information density, parameter placement and edit wording. What it may not do is change a character, an action, a location, the light, or a narrative relationship. The project states the rule as two lines:

```text
MODEL SYNTAX MAY CHANGE.
SCENE LOGIC MAY NOT.
```

That constraint is what makes transcoding safe. Change the model and you get a different rendering of the same shot; change the shot and the compiler has done something the user never asked for.

## USER-LOCKED beats the reference image

The decoder in version 2.3 makes a distinction that resolves most arguments about style references: what belongs to the reference image, and what belongs to you.

Visual choices you specify are marked as user-locked. A reference cannot override them. Composition, shot size, viewpoint, how much of the frame a character occupies, and the aspect ratio are all in that category if you name them.

Everything you do not specify stays open, and an open choice may be retained from the reference, adapted, filled in, or dropped.

The worked example makes the rule concrete. If you say you want that style but a chest-up portrait of the character, the shot size is yours and the reference does not get to push it back to a wide shot. What carries over is the compatible exposure, colour, material and viewing relationship.

The framing in the source material is that a reference image is not a command and the new scene is. The sentence attached to the example is that the visual logic is preserved without copying the reference's coordinates.

For anyone who has watched a style reference override a deliberate composition choice, that is the feature to look for, and it is the one most prompt tools get wrong.

## A decode card is not a prompt

The claim made about the decoder is that it is not ordinary image-to-prompt. It does not compress a picture into a list of adjectives, and the adjectives are named as the failure mode: cinematic, moody, soft light, film grain.

Instead it asks what actually constitutes the image's visual language. The example is a dark rider against an orange-red herd in coarse grain. The decoder is described as noticing the relationship between a dark subject and an unstable bright group, large areas of dark that carry no information, a subject that keeps its silhouette but loses its internal detail, grain that crosses both the light and the dark, the bloom that blends object edges, and the fact that what a person is looking at matters more than the specific herd.

The rider, the herd and the outdoor place are source content. The dark structure, the colour tension, the coarse grain, the edge bloom and the viewing relationship survive the change of scene. The line attached to it is that visual logic transfers and new scene intent is preserved.

The output is a card, and the card is defined by what it is not: not a raw prompt, not an image description, not a database record, not an instruction for copying the picture. It holds the primary medium and its constraints, the full set of core visual rules, the visual grammar, an expression mechanism when there is evidence for one, plus the transfer scope, the allowed changes, the source residue and invalidation alerts.

The practical payoff is stated as a workflow: decode once, and the originals can leave. Next time you ask for an old wizard in a subway station using that card, the compile runs from the card.

## Eight rules are kept, three to five are activated

The card is described in layers, and the layer boundaries are what stop it becoming a wall of text.

Scene Facts is what the original picture literally contains. Those do not get copied just because you asked for its style. Visual Grammar is how the picture is organised and expressed. Expression Mechanism is the key visual event the work performs, and it is only extracted when there is clear evidence for it, which is a guard against inventing intent.

Core Visual Rules are the reusable set, and the count is bounded: five to eight rules are kept in full. Active Core Rules is a smaller set, three to five, selected for the scene currently being made.

Transfer Scope grades what may cross over, with three values: strong, conditional, and do not transfer. Source Residue lists the characters, clothing, locations, text, brands and props from the original that must not leak into the new scene.

Then the rule that keeps the whole thing honest: the full card does not go into the final prompt. A compiler priority gate selects only what the scene needs.

There is also a precedence rule with a name in capitals: reference medium overrides default cinematic realism. A paper illustration is not automatically turned into a film still, stylised 3D does not default to photoreal rendering, and an old game screenshot is not upgraded to a modern look. A photographic reference keeps photographic logic; a non-photographic one keeps its own paper, paint, line, edge, form and rendering language.

## Each reference gets a job

Uploading several reference images does not average them, and that is the specified behaviour.

With four images, each is assigned a role. One is responsible for the colour relationship between soft pink-purple, sage green and warm white. Another is responsible for a vertical axis and a large circle composition at the bottom. A third carries the temperature, the proportions and the sense of presence of a real person. The fourth carries mirror chrome and true reflections.

Each does its job, and the contents of the four are not blended together. Conflicting media are not averaged simply because they arrived at the same time.

The line attached to the example is that one reference does not have to explain everything. That is a design decision about how people use references: you rarely want a single look, you want a set of properties, and the previous behaviour of averaging everything into one mush is what made multi-reference uploads disappointing.

A reference role router sits before the decoder in the pipeline, and a medium router sits after it, so a reference is classified by what kind of thing it is before anything tries to learn from it. On top of that sits a repair step in the pipeline, which the version notes list alongside the router, the decoder, the core visual rules, the transfer scope and the card itself as things introduced in version 2.2.

## The router picks an adapter, not a winner

There are four native adapters, and what each one optimises for is stated in a small table.

GPT Image 2.5 compiles into a clear natural-language visual description with edit instructions. Midjourney V8.2 compiles into a natural, compact description with explicit relationships, placing parameters at the end when the task needs them. Seedream 5.0 Pro compiles into clear space, subject relationships and a visual brief. Nano Banana compiles into direct task wording suited to multiple rounds of editing.

What the router is not is stated just as plainly. It is a task heuristic, not a permanent ranking, and it makes no claim that one model is best. Model capabilities and interfaces change, and the source material says so directly.

The Midjourney adapter's update is described in the same spirit: at version 8.2 it keeps natural visual relationships by default, distinguishes the image generation model from the edit model, and selects parameters per task rather than applying fixed suffixes carried over from an older version.

The comparison page makes a related point about expectation. Four results are shown from one Scene Master with the same core constraints, and the text says they are not the same picture and that pixel-level consistency is not promised. The difference is the adapter plus the model's own interpretation.

## Adapter updates change the compiler, not the architecture

The release history shows a project that updates its model baselines without touching its structure, and the recent tags say so in their titles.

Version 2.1.0 migrated Midjourney compilation to the V8.2 capability baseline, updating prompt compilation, edit model routing, reference strategy, parameter handling and the transcode behaviour. Version 2.1.1 moved the OpenAI image adapter baseline to the 2.5 generation, and it states that the Scene Master and Model Compiler architecture is unchanged.

The method behind that update is the useful part. Following the vendor's own migration guidance, a prompt that already works on the previous version should be tested unchanged against the new one first. The first comparison is supposed to hold the prompt, the references, the scene facts, the aspect intent and the constraints constant, and only then fix whichever variable actually failed, rather than rewriting the prompt because the version number changed.

The release notes are also careful about what the vendor's headline number means. Generation latency is described as reduced by up to fifty percent relative to the earlier version, and the text immediately adds that this ratio describes latency and is not a ratio of image quality improvement.

That distinction is the whole discipline of the tool: measure the variable that changed, and nothing else.

## It writes prompts, it does not call an API

The scope is worth stating plainly, because the name invites the wrong assumption.

The skill generates visual plans and prompts inside ChatGPT and Codex. It does not lock the underlying model and it does not call an API automatically.

There is one conditional path. Only when the user asks for an API does the router consider two named options per task, one for fast high-quality generation and one for high-precision editing at a longer generation time. The material is explicit that this is not a permanent ranking.

The naming carries a similar warning. The outward brand is the Chinese name with an English one alongside it, but the technical name stays fixed for compatibility, so the install path, the automatic trigger and the explicit invocation all keep working. A reader looking for the skill directory will find it under that fixed name rather than the brand.

The repository layout matches a prompt library rather than an application: a skill directory, documentation, scripts, a changelog, release notes, and reference files inside the skill, one per model family, each with a verification date recorded in the text.

So the deliverable is a prompt plus a card, produced inside a chat client you already have. Nothing here is a pipeline you run.

## Conclusion

Adopt zy-cinematic-realism if you generate images from more than one model and keep re-explaining the same shot, since the Scene Master exists to stop the visual design being rewritten on every compile. Do not adopt it as an image generator or an API wrapper, because the project states plainly that it produces plans and prompts inside the chat client and only considers an API route when you ask for one. Verify two things first. Decide which constraints are non-negotiable in your shots and state them as user-locked, because the decoder is explicitly allowed to override anything you leave open. Then run one comparison with a single variable changed, since that is how the project expects you to attribute a failure to a model rather than to the prompt.

## FAQ

### What does zy-cinematic-realism do?

It is a cinematic visual workflow for ChatGPT and Codex. You give it a scene, it locks that design into a Scene Master, and then compiles it into a native prompt for the target model, with the rule that model syntax may change while scene logic may not.

### How does it handle a style reference image?

The decoder separates what belongs to the original picture from what constitutes its visual language. Choices you specify are user-locked and a reference cannot override them, while unspecified choices stay open and may be retained, adapted or dropped from the reference.

### What is a decode card?

The reusable output of reading a reference image. It stores the primary medium and its constraints, five to eight core visual rules, the visual grammar, an expression mechanism when there is evidence for one, the transfer scope, the allowed changes, the source residue and invalidation alerts. It is not a prompt or an image description.

### Which image models does zy-cinematic-realism compile for?

Four: GPT Image 2.5, Midjourney V8.2, Seedream 5.0 Pro and Nano Banana. The router selects among them as a task heuristic rather than as a ranking, and each adapter optimises for a different target, from clear natural-language descriptions to compact wording suited to multiple rounds of editing.

### Does zy-cinematic-realism call an image API?

Not automatically. It generates visual plans and prompts inside ChatGPT and Codex without locking the underlying model. Only when a user asks for an API does the router consider the fast generation or the precise editing option for that task.

## Sources

- [Issues](https://github.com/popopo-99/zy-cinematic-realism/issues)
- [popopo-99/zy-cinematic-realism on GitHub](https://github.com/popopo-99/zy-cinematic-realism)
- [README](https://github.com/popopo-99/zy-cinematic-realism/blob/main/README.md)
- [Releases](https://github.com/popopo-99/zy-cinematic-realism/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/popopo-99-zy-cinematic-realism